feature: Add additional headers_sent informations to the EmitterException

composer.json

@@ -49,7 +49,7 @@
             "LaminasTest\\HttpHandlerRunner\\": "test/"
         },
         "files": [
-            "test/TestAsset/SapiResponse.php"
+            "test/TestAsset/HeadersSent.php"
         ]
     },
     "scripts": {

src/Emitter/SapiEmitterTrait.php

@@ -11,6 +11,7 @@
 use function function_exists;
 use function header;
 use function headers_sent;
+use function is_int;
 use function is_string;
 use function ob_get_length;
 use function ob_get_level;
@@ -30,8 +31,11 @@ trait SapiEmitterTrait
      */
     private function assertNoPreviousOutput(): void
     {
-        if ($this->headersSent()) {
-            throw EmitterException::forHeadersSent();
+        $filename = null;
+        $line     = null;
+        if ($this->headersSent($filename, $line)) {
+            assert(is_string($filename) && is_int($line));
+            throw EmitterException::forHeadersSent($filename, $line);
         }
 
         if (ob_get_level() > 0 && ob_get_length() > 0) {
@@ -99,14 +103,14 @@ private function filterHeader(string $header): string
         return ucwords($header, '-');
     }
 
-    private function headersSent(): bool
+    private function headersSent(?string &$filename = null, ?int &$line = null): bool
     {
         if (function_exists('Laminas\HttpHandlerRunner\Emitter\headers_sent')) {
             // phpcs:ignore SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly.ReferenceViaFullyQualifiedName
-            return \Laminas\HttpHandlerRunner\Emitter\headers_sent();
+            return \Laminas\HttpHandlerRunner\Emitter\headers_sent($filename, $line);
         }
 
-        return headers_sent();
+        return headers_sent($filename, $line);
     }
 
     private function header(string $headerName, bool $replace, int $statusCode): void

src/Exception/EmitterException.php

@@ -6,11 +6,13 @@
 
 use RuntimeException;
 
+use function sprintf;
+
 class EmitterException extends RuntimeException implements ExceptionInterface
 {
-    public static function forHeadersSent(): self
+    public static function forHeadersSent(string $filename, int $line): self
     {
-        return new self('Unable to emit response; headers already sent');
+        return new self(sprintf('Unable to emit response; headers already sent in %s:%d', $filename, $line));
     }
 
     public static function forOutputSent(): self

test/Emitter/AbstractEmitterTest.php

@@ -6,13 +6,17 @@
 
 use Laminas\Diactoros\Response;
 use Laminas\HttpHandlerRunner\Emitter\EmitterInterface;
+use Laminas\HttpHandlerRunner\Emitter\HeadersSent;
 use Laminas\HttpHandlerRunner\Emitter\SapiEmitter;
+use Laminas\HttpHandlerRunner\Exception\EmitterException;
 use LaminasTest\HttpHandlerRunner\TestAsset\HeaderStack;
 use PHPUnit\Framework\TestCase;
+use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\StreamInterface;
 
 use function ob_end_clean;
 use function ob_start;
+use function sprintf;
 
 abstract class AbstractEmitterTest extends TestCase
 {
@@ -22,12 +26,14 @@ abstract class AbstractEmitterTest extends TestCase
     public function setUp(): void
     {
         HeaderStack::reset();
+        HeadersSent::reset();
         $this->emitter = new SapiEmitter();
     }
 
     public function tearDown(): void
     {
         HeaderStack::reset();
+        HeadersSent::reset();
     }
 
     public function testEmitsResponseHeaders(): void
@@ -108,4 +114,20 @@ public function testDoesNotInjectContentLengthHeaderIfStreamSizeIsUnknown(): voi
             self::assertStringNotContainsString('Content-Length:', $header['header']);
         }
     }
+
+    public function testWillThrowEmitterExceptionWhenHeadersAreAlreadySent(): void
+    {
+        $sentInLine = __LINE__;
+        HeadersSent::markSent(__FILE__, $sentInLine);
+
+        $this->expectException(EmitterException::class);
+        $this->expectExceptionMessage(
+            sprintf(
+                'Unable to emit response; headers already sent in %s:%d',
+                __FILE__,
+                $sentInLine
+            )
+        );
+        $this->emitter->emit($this->createMock(ResponseInterface::class));
+    }
 }

test/TestAsset/HeadersSent.php

@@ -0,0 +1,58 @@
+<?php // phpcs:disable WebimpressCodingStandard.NamingConventions.ValidVariableName.NotCamelCaps
+
+
+declare(strict_types=1);
+
+namespace Laminas\HttpHandlerRunner\Emitter;
+
+use LaminasTest\HttpHandlerRunner\TestAsset\HeaderStack;
+
+final class HeadersSent
+{
+    /** @var bool */
+    private static $headerSent = false;
+    /** @var null|string */
+    public static $filename;
+    /** @var null|int */
+    public static $line;
+
+    public static function reset(): void
+    {
+        self::$headerSent = false;
+        self::$filename   = null;
+        self::$line       = null;
+    }
+
+    public static function markSent(string $filename, int $line): void
+    {
+        self::$headerSent = true;
+        self::$filename   = $filename;
+        self::$line       = $line;
+    }
+
+    public static function sent(): bool
+    {
+        return self::$headerSent;
+    }
+}
+
+function headers_sent(?string &$filename = null, ?int &$line = null): bool
+{
+    $filename = HeadersSent::$filename;
+    $line     = HeadersSent::$line;
+    return HeadersSent::sent();
+}
+
+/**
+ * Emit a header, without creating actual output artifacts
+ */
+function header(string $headerName, bool $replace = true, ?int $httpResponseCode = null): void
+{
+    HeaderStack::push(
+        [
+            'header'      => $headerName,
+            'replace'     => $replace,
+            'status_code' => $httpResponseCode,
+        ]
+    );
+}