Add extra responses

Author: coisa

src/EmptyResponse.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of php-fast-forward/http-message.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @link      https://github.com/php-fast-forward/http-message
+ * @copyright Copyright (c) 2025 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ */
+
+namespace FastForward\Http\Message;
+
+use Nyholm\Psr7\Response;
+
+/**
+ * Class EmptyResponse.
+ *
+ * Represents an HTTP 204 No Content response.
+ *
+ * This class MUST be used when generating responses that intentionally contain no body content,
+ * in compliance with RFC 9110. It automatically sets the HTTP status code to 204 (No Content)
+ * and applies an optional set of headers.
+ *
+ * @package FastForward\Http\Message
+ */
+final class EmptyResponse extends Response
+{
+    /**
+     * Constructs a new EmptyResponse instance with optional headers.
+     *
+     * This constructor SHALL initialize the response with HTTP status 204 and no body content.
+     * The 'reason' phrase for status 204 is automatically included based on StatusCode enumeration.
+     *
+     * @param array<string, string|string[]> $headers optional headers to include in the response
+     */
+    public function __construct(array $headers = [])
+    {
+        parent::__construct(
+            status: StatusCode::NoContent->value,
+            headers: $headers,
+            reason: StatusCode::NoContent->getReasonPhrase(),
+        );
+    }
+}

src/JsonResponseInterface.php

@@ -25,4 +25,4 @@
  *
  * This interface SHALL be used to identify responses intended to transmit JSON-encoded payloads with proper headers.
  */
-interface JsonResponseInterface extends ResponseInterface, PayloadAwareInterface {}
+interface JsonResponseInterface extends ResponseInterface, PayloadAwareInterface, PayloadImmutableInterface {}

src/JsonStream.php

@@ -47,9 +47,9 @@ final class JsonStream extends Stream implements JsonStreamInterface
     private mixed $payload = [];
 
     /**
-     * @var int The JSON encoding options to be applied. Defaults to self::ENCODING_OPTIONS.
+     * @var int the JSON encoding options to be applied
      */
-    private int $encodingOptions = self::ENCODING_OPTIONS;
+    private int $encodingOptions;
 
     /**
      * Constructs a new JsonStream instance with the provided payload.
@@ -95,7 +95,7 @@ public function getPayload(): mixed
      */
     public function withPayload(mixed $payload): self
     {
-        return new self($payload);
+        return new self($payload, $this->encodingOptions);
     }
 
     /**

src/JsonStreamInterface.php

@@ -25,4 +25,4 @@
  *
  * @package FastForward\Http\Message
  */
-interface JsonStreamInterface extends StreamInterface, PayloadAwareInterface {}
+interface JsonStreamInterface extends StreamInterface, PayloadAwareInterface, PayloadImmutableInterface {}

src/PayloadAwareInterface.php

@@ -35,17 +35,4 @@ interface PayloadAwareInterface
      * @return mixed the payload, which MAY be of any type including array, object, scalar, or null
      */
     public function getPayload(): mixed;
-
-    /**
-     * Returns a new instance with the specified payload.
-     *
-     * This method MUST NOT modify the current instance. It SHALL return a new instance with the updated payload.
-     * The payload MAY be of any type supported by the implementation. Implementations MAY throw exceptions if
-     * constraints on the payload type are violated.
-     *
-     * @param mixed $payload the new payload to set in the instance
-     *
-     * @return self a new instance with the updated payload
-     */
-    public function withPayload(mixed $payload): self;
 }

src/PayloadImmutableInterface.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of php-fast-forward/http-message.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @link      https://github.com/php-fast-forward/http-message
+ * @copyright Copyright (c) 2025 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ */
+
+namespace FastForward\Http\Message;
+
+/**
+ * Interface PayloadAwareInterface.
+ *
+ * Defines functionality for objects that encapsulate and manage a payload.
+ * Implementations of this interface MUST provide immutable methods for accessing and replacing the payload.
+ * The payload MAY be of any type supported by the implementation, including arrays, objects, scalars, or null.
+ *
+ * @package FastForward\Http\Message
+ *
+ * @internal
+ */
+interface PayloadImmutableInterface
+{
+    /**
+     * Returns a new instance with the specified payload.
+     *
+     * This method MUST NOT modify the current instance. It SHALL return a new instance with the updated payload.
+     * The payload MAY be of any type supported by the implementation. Implementations MAY throw exceptions if
+     * constraints on the payload type are violated.
+     *
+     * @param mixed $payload the new payload to set in the instance
+     *
+     * @return self a new instance with the updated payload
+     */
+    public function withPayload(mixed $payload): self;
+}

src/RedirectResponse.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of php-fast-forward/http-message.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @link      https://github.com/php-fast-forward/http-message
+ * @copyright Copyright (c) 2025 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ */
+
+namespace FastForward\Http\Message;
+
+use Nyholm\Psr7\Response;
+use Psr\Http\Message\UriInterface;
+
+/**
+ * Class RedirectResponse.
+ *
+ * Represents an HTTP redirect response with customizable status codes for temporary or permanent redirects.
+ * This class MUST be used for generating HTTP responses that instruct clients to navigate to a different location,
+ * by automatically setting the 'Location' header.
+ *
+ * @package FastForward\Http\Message
+ */
+final class RedirectResponse extends Response
+{
+    /**
+     * Constructs a new RedirectResponse instance.
+     *
+     * This constructor SHALL set the 'Location' header and apply the appropriate HTTP status code
+     * for temporary (302 Found) or permanent (301 Moved Permanently) redirects.
+     *
+     * @param string|UriInterface            $uri       The target URI for redirection. MUST be absolute or relative according to context.
+     * @param bool                           $permanent if true, the response status will be 301 (permanent redirect); otherwise, 302 (temporary redirect)
+     * @param array<string, string|string[]> $headers   optional additional headers to include in the response
+     */
+    public function __construct(string|UriInterface $uri, bool $permanent = false, array $headers = [])
+    {
+        $headers['Location'] = (string) $uri;
+        $status              = $permanent ? StatusCode::MovedPermanently : StatusCode::Found;
+
+        parent::__construct(
+            status: $status->value,
+            headers: $headers,
+            reason: $status->getReasonPhrase(),
+        );
+    }
+}

tests/EmptyResponseTest.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of php-fast-forward/http-message.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @link      https://github.com/php-fast-forward/http-message
+ * @copyright Copyright (c) 2025 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ */
+
+namespace FastForward\Http\Message\Tests;
+
+use FastForward\Http\Message\EmptyResponse;
+use FastForward\Http\Message\StatusCode;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+#[CoversClass(EmptyResponse::class)]
+#[UsesClass(StatusCode::class)]
+final class EmptyResponseTest extends TestCase
+{
+    public function testConstructorWillSetNoContentStatusAndEmptyBody(): void
+    {
+        $response = new EmptyResponse();
+
+        self::assertSame(StatusCode::NoContent->value, $response->getStatusCode());
+        self::assertSame(StatusCode::NoContent->getReasonPhrase(), $response->getReasonPhrase());
+        self::assertSame('', (string) $response->getBody());
+    }
+
+    public function testConstructorWillPreserveAdditionalHeaders(): void
+    {
+        $headers = [
+            'X-Test-Header' => 'value',
+            'X-Multiple'    => ['one', 'two'],
+        ];
+
+        $response = new EmptyResponse($headers);
+
+        self::assertSame('value', $response->getHeaderLine('X-Test-Header'));
+        self::assertSame('one, two', $response->getHeaderLine('X-Multiple'));
+        self::assertSame(StatusCode::NoContent->value, $response->getStatusCode());
+        self::assertSame('', (string) $response->getBody());
+    }
+}

tests/RedirectResponseTest.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of php-fast-forward/http-message.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @link      https://github.com/php-fast-forward/http-message
+ * @copyright Copyright (c) 2025 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ */
+
+namespace FastForward\Http\Message\Tests;
+
+use FastForward\Http\Message\RedirectResponse;
+use FastForward\Http\Message\StatusCode;
+use Nyholm\Psr7\Uri;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+#[CoversClass(RedirectResponse::class)]
+#[UsesClass(StatusCode::class)]
+final class RedirectResponseTest extends TestCase
+{
+    public function testConstructorWillSetLocationHeaderAndTemporaryStatus(): void
+    {
+        $uri = 'https://example.com';
+
+        $response = new RedirectResponse($uri);
+
+        self::assertSame(StatusCode::Found->value, $response->getStatusCode());
+        self::assertSame(StatusCode::Found->getReasonPhrase(), $response->getReasonPhrase());
+        self::assertSame('https://example.com', $response->getHeaderLine('Location'));
+    }
+
+    public function testConstructorWillSetLocationHeaderAndPermanentStatus(): void
+    {
+        $uri = 'https://example.com/redirect';
+
+        $response = new RedirectResponse($uri, permanent: true);
+
+        self::assertSame(StatusCode::MovedPermanently->value, $response->getStatusCode());
+        self::assertSame(StatusCode::MovedPermanently->getReasonPhrase(), $response->getReasonPhrase());
+        self::assertSame('https://example.com/redirect', $response->getHeaderLine('Location'));
+    }
+
+    public function testConstructorAcceptsUriInterfaceInstance(): void
+    {
+        $uri = new Uri('/relative/path');
+
+        $response = new RedirectResponse($uri);
+
+        self::assertSame('/relative/path', $response->getHeaderLine('Location'));
+    }
+
+    public function testConstructorWillPreserveAdditionalHeaders(): void
+    {
+        $uri     = 'https://example.com';
+        $headers = [
+            'X-Custom-Header' => 'test-value',
+        ];
+
+        $response = new RedirectResponse($uri, permanent: false, headers: $headers);
+
+        self::assertSame('test-value', $response->getHeaderLine('X-Custom-Header'));
+        self::assertSame('https://example.com', $response->getHeaderLine('Location'));
+    }
+}