Merging develop to master in preparation for 1.6.0 release

Author: weierophinney

CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
+## 1.6.0 - TBD
+
+### Added
+
+- Nothing.
+
+### Changed
+
+- [#270](https://github.com/zendframework/zend-diactoros/pull/270) changes the
+  behavior of `Zend\Diactoros\Server`: it no longer creates an output buffer.
+
+- [#270](https://github.com/zendframework/zend-diactoros/pull/270) changes the
+  behavior of the two SAPI emitters in two backwards-incompatible ways:
+
+  - They no longer auto-inject a `Content-Length` header. If you need this
+    functionality, zendframework/zend-expressive-helpers 4.1+ provides it via
+    `Zend\Expressive\Helper\ContentLengthMiddleware`.
+
+  - They no longer flush the output buffer. Instead, if headers have been sent,
+    or the output buffer exists and has a non-zero length, the emitters raise an
+    exception, as mixed PSR-7/output buffer content creates a blocking issue.
+    If you are emitting content via `echo`, `print`, `var_dump`, etc., or not
+    catching PHP errors or exceptions, you will need to either fix your
+    application to always work with a PSR-7 response, or provide your own
+    emitters that allow mixed output mechanisms.
+
+### Deprecated
+
+- Nothing.
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- Nothing.
+
 ## 1.5.1 - TBD
 
 ### Added

doc/book/emitting-responses.md

@@ -3,10 +3,15 @@
 If you are using a non-SAPI PHP implementation and wish to use the `Server` class, or if you do not
 want to use the `Server` implementation but want to emit a response, this package provides an
 interface, `Zend\Diactoros\Response\EmitterInterface`, defining a method `emit()` for emitting the
-response. A single implementation is currently available, `Zend\Diactoros\Response\SapiEmitter`,
-which will use the native PHP functions `header()` and `echo` in order to emit the response. If you
-are using a non-SAPI implementation, you will need to create your own `EmitterInterface`
-implementation.
+response.
+
+Diactoros provides two implementations currently, both for working with
+traditional Server API (SAPI) implementations: `Zend\Diactoros\Response\SapiEmitter`
+and `Zend\Diactoros\Response\SapiStreamEmitter`.  Each uses the native `header()`
+PHP function to emit headers, and `echo()` to emit the response body.
+
+If you are using a non-SAPI implementation, you will need to create your own
+`EmitterInterface` implementation.
 
 For example, the `SapiEmitter` implementation of the `EmitterInterface` can be used thus:
 
@@ -16,3 +21,43 @@ $response->getBody()->write("some content\n");
 $emitter = new Zend\Diactoros\Response\SapiEmitter();
 $emitter->emit($response);
 ```
+
+## Emitting ranges of streamed files
+
+The `SapiStreamEmitter` is useful when you want to emit a `Content-Range`. As an
+example, to stream a range of bytes from a file to a client, the client can pass
+the following header:
+
+```http
+Range: bytes=1024-2047
+```
+
+Your application would then populate the response with a `Content-Range` header:
+
+```php
+$range = $request->getHeaderLine('range');
+$range = str_replace('=', ' ', $range);
+
+$body = new Stream($pathToFile);
+$size = $body->getSize();
+$range .= '/' . $size;
+
+$response = new Response($body);
+$response = $response->withHeader('Content-Range', $range);
+```
+
+> Note: you will likely want to ensure the range specified falls within the
+> content size of the streamed body!
+
+The `SapiStreamEmitter` detects the `Content-Range` header and emits only the
+bytes specified.
+
+```php
+$emitter = new SapiStreamEmitter();
+$emitter->emit($response);
+```
+
+The `SapiStreamEmitter` may be used in place of the `SapiEmitter`, even when not
+sending files. However, unlike the `SapiEmitter`, it will emit a chunk of
+content at a time instead of the full content at once, which could lead to
+performance overhead. The default chunk size is 8192 bytes.

src/Response/SapiEmitter.php

@@ -23,19 +23,13 @@ class SapiEmitter implements EmitterInterface
      * body content via the output buffer.
      *
      * @param ResponseInterface $response
-     * @param null|int $maxBufferLevel Maximum output buffering level to unwrap.
      */
-    public function emit(ResponseInterface $response, $maxBufferLevel = null)
+    public function emit(ResponseInterface $response)
     {
-        if (headers_sent()) {
-            throw new RuntimeException('Unable to emit response; headers already sent');
-        }
-
-        $response = $this->injectContentLength($response);
+        $this->assertNoPreviousOutput();
 
         $this->emitStatusLine($response);
         $this->emitHeaders($response);
-        $this->flush($maxBufferLevel);
         $this->emitBody($response);
     }
 

src/Response/SapiEmitterTrait.php

@@ -10,26 +10,28 @@
 namespace Zend\Diactoros\Response;
 
 use Psr\Http\Message\ResponseInterface;
+use RuntimeException;
 
 trait SapiEmitterTrait
 {
     /**
-     * Inject the Content-Length header if is not already present.
+     * Checks to see if content has previously been sent.
      *
-     * @param ResponseInterface $response
-     * @return ResponseInterface
+     * If either headers have been sent or the output buffer contains content,
+     * raises an exception.
+     *
+     * @throws RuntimeException if headers have already been sent.
+     * @throws RuntimeException if output is present in the output buffer.
      */
-    private function injectContentLength(ResponseInterface $response)
+    private function assertNoPreviousOutput()
     {
-        if (! $response->hasHeader('Content-Length')) {
-            // PSR-7 indicates int OR null for the stream size; for null values,
-            // we will not auto-inject the Content-Length.
-            if (null !== $response->getBody()->getSize()) {
-                return $response->withHeader('Content-Length', (string) $response->getBody()->getSize());
-            }
+        if (headers_sent()) {
+            throw new RuntimeException('Unable to emit response; headers already sent');
         }
 
-        return $response;
+        if (ob_get_level() > 0 && ob_get_length() > 0) {
+            throw new RuntimeException('Output has been emitted previously; cannot emit response');
+        }
     }
 
     /**
@@ -77,23 +79,6 @@ private function emitHeaders(ResponseInterface $response)
         }
     }
 
-    /**
-     * Loops through the output buffer, flushing each, before emitting
-     * the response.
-     *
-     * @param int|null $maxBufferLevel Flush up to this buffer level.
-     */
-    private function flush($maxBufferLevel = null)
-    {
-        if (null === $maxBufferLevel) {
-            $maxBufferLevel = ob_get_level();
-        }
-
-        while (ob_get_level() > $maxBufferLevel) {
-            ob_end_flush();
-        }
-    }
-
     /**
      * Filter a header name to wordcase
      *

src/Response/SapiStreamEmitter.php

@@ -24,20 +24,13 @@ class SapiStreamEmitter implements EmitterInterface
      * body content via the output buffer.
      *
      * @param ResponseInterface $response
-     * @param null|int $maxBufferLevel Maximum output buffering level to unwrap.
      * @param int $maxBufferLength Maximum output buffering size for each iteration
      */
-    public function emit(ResponseInterface $response, $maxBufferLevel = null, $maxBufferLength = 8192)
+    public function emit(ResponseInterface $response, $maxBufferLength = 8192)
     {
-        if (headers_sent()) {
-            throw new RuntimeException('Unable to emit response; headers already sent');
-        }
-
-        $response = $this->injectContentLength($response);
-
+        $this->assertNoPreviousOutput();
         $this->emitStatusLine($response);
         $this->emitHeaders($response);
-        $this->flush($maxBufferLevel);
 
         $range = $this->parseContentRange($response->getHeaderLine('Content-Range'));
 

src/Server.php

@@ -150,24 +150,18 @@ public static function createServerFromRequest(
      * If provided a $finalHandler, that callable will be used for
      * incomplete requests.
      *
-     * Output buffering is enabled prior to invoking the attached
-     * callback; any output buffered will be sent prior to any
-     * response body content.
-     *
      * @param null|callable $finalHandler
      */
     public function listen(callable $finalHandler = null)
     {
         $callback = $this->callback;
 
-        ob_start();
-        $bufferLevel = ob_get_level();
-
         $response = $callback($this->request, $this->response, $finalHandler);
         if (! $response instanceof ResponseInterface) {
             $response = $this->response;
         }
-        $this->getEmitter()->emit($response, $bufferLevel);
+
+        $this->getEmitter()->emit($response);
     }
 
     /**

test/Response/AbstractEmitterTest.php

@@ -44,7 +44,6 @@ public function testEmitsResponseHeaders()
         ob_end_clean();
         $this->assertContains('HTTP/1.1 200 OK', HeaderStack::stack());
         $this->assertContains('Content-Type: text/plain', HeaderStack::stack());
-        $this->assertContains('Content-Length: 8', HeaderStack::stack());
     }
 
     public function testEmitsMessageBody()

test/Response/SapiEmitterTest.php

@@ -13,26 +13,4 @@
 
 class SapiEmitterTest extends AbstractEmitterTest
 {
-    public function testEmitsBufferLevel()
-    {
-        ob_start();
-        echo "level" . ob_get_level() . " "; // 2
-        ob_start();
-        echo "level" . ob_get_level() . " "; // 3
-        ob_start();
-        echo "level" . ob_get_level() . " "; // 4
-        $response = (new Response())
-            ->withStatus(200)
-            ->withAddedHeader('Content-Type', 'text/plain');
-        $response->getBody()->write('Content!');
-        ob_start();
-        $this->emitter->emit($response);
-        $this->assertSame('Content!', ob_get_contents());
-        ob_end_clean();
-        $this->assertSame('level4 ', ob_get_contents(), 'current buffer level string must remains after emit');
-        ob_end_clean();
-        $this->emitter->emit($response, 2);
-        $this->assertSame('level2 level3 Content!', ob_get_contents(), 'must buffer until specified level');
-        ob_end_clean();
-    }
 }

test/Response/SapiStreamEmitterTest.php

@@ -210,7 +210,7 @@ function ($bufferLength) use (& $peakBufferLength) {
             ->withBody($stream->reveal());
 
         ob_start();
-        $this->emitter->emit($response, null, $maxBufferLength);
+        $this->emitter->emit($response, $maxBufferLength);
         $emittedContents = ob_get_clean();
 
         if ($seekable) {
@@ -351,7 +351,7 @@ function ($bufferLength) use (& $peakBufferLength) {
             ->withBody($stream->reveal());
 
         ob_start();
-        $this->emitter->emit($response, null, $maxBufferLength);
+        $this->emitter->emit($response, $maxBufferLength);
         $emittedContents = ob_get_clean();
 
         $stream->rewind()->shouldNotBeCalled();
@@ -497,7 +497,7 @@ function () use (& $closureTrackMemoryUsage) {
 
         gc_disable();
 
-        $this->emitter->emit($response, null, $maxBufferLength);
+        $this->emitter->emit($response, $maxBufferLength);
 
         ob_end_flush();