add stream proxying example

Author: michalsn

user_guide_src/source/outgoing/response.rst

@@ -284,6 +284,15 @@ total size (for example, when proxying a stream of known length), you may set
     which sends proper ``Content-Length`` and ``Content-Disposition`` headers.
     Use ``StreamResponse`` when the content is generated while it is being sent.
 
+Example: Proxying an Upstream Stream
+------------------------------------
+
+``StreamResponse`` can forward a stream from another source - such as object
+storage or an internal API - to the client without buffering it in memory or
+writing it to disk:
+
+.. literalinclude:: response/041.php
+
 The :ref:`development server <sse-development-server>` and
 :ref:`production <sse-production>` considerations described for SSE below apply
 to all streaming responses.

user_guide_src/source/outgoing/response/041.php

@@ -0,0 +1,24 @@
+<?php
+
+use CodeIgniter\HTTP\StreamResponse;
+
+$stream = $this->response->stream(static function (StreamResponse $stream) {
+    // Forward the upstream file chunk by chunk, without buffering it in memory
+    $source = fopen('https://storage.internal/reports/annual.pdf', 'rb');
+
+    try {
+        while (! feof($source)) {
+            $chunk = fread($source, 1_048_576);
+
+            if ($chunk === false || ! $stream->write($chunk)) {
+                break;
+            }
+        }
+    } finally {
+        fclose($source);
+    }
+});
+
+$stream->setContentType('application/pdf');
+
+return $stream;