Update PHPDoc

Author: coisa

src/JsonResponse.php

@@ -18,10 +18,25 @@
 use Nyholm\Psr7\Response;
 
 /**
- * @method getBody(): JsonStreamInterface
+ * Class JsonResponse.
+ *
+ * Provides a JSON-specific HTTP response implementation that complies with PSR-7 Response interfaces.
+ * This class MUST be used when returning JSON payloads over HTTP responses.
+ * It automatically sets the 'Content-Type' header to 'application/json' with the specified charset.
+ *
+ * @method JsonStreamInterface getBody() Retrieves the response body as a JSON stream.
  */
 final class JsonResponse extends Response implements JsonResponseInterface
 {
+    /**
+     * Constructs a new JsonResponse instance with an optional payload and charset.
+     *
+     * This constructor SHALL initialize the response body with a JsonStream containing the provided payload.
+     * The 'Content-Type' header MUST be set to 'application/json' with the specified charset.
+     *
+     * @param mixed  $payload The JSON-serializable payload to send in the response body. Defaults to an empty array.
+     * @param string $charset The character encoding to use in the 'Content-Type' header. Defaults to 'utf-8'.
+     */
     public function __construct(
         mixed $payload = [],
         string $charset = 'utf-8'
@@ -32,11 +47,29 @@ public function __construct(
         );
     }
 
+    /**
+     * Retrieves the payload contained in the response body.
+     *
+     * This method MUST return the same payload provided during construction or via withPayload().
+     *
+     * @return mixed the decoded JSON payload
+     */
     public function getPayload(): mixed
     {
         return $this->getBody()->getPayload();
     }
 
+    /**
+     * Returns an instance with the specified payload.
+     *
+     * This method SHALL return a new instance of the response with the body replaced by a new JsonStream
+     * containing the provided payload. The original instance MUST remain unchanged, ensuring immutability
+     * as required by PSR-7.
+     *
+     * @param mixed $payload the new JSON-serializable payload
+     *
+     * @return self a new JsonResponse instance with the updated payload
+     */
     public function withPayload(mixed $payload): self
     {
         return $this->withBody($this->getBody()->withPayload($payload));

src/JsonResponseInterface.php

@@ -17,4 +17,12 @@
 
 use Psr\Http\Message\ResponseInterface;
 
+/**
+ * Interface JsonResponseInterface.
+ *
+ * Defines the contract for JSON-specific HTTP response implementations.
+ * Implementations of this interface MUST provide access to a JSON payload and comply with PSR-7 ResponseInterface.
+ *
+ * This interface SHALL be used to identify responses intended to transmit JSON-encoded payloads with proper headers.
+ */
 interface JsonResponseInterface extends ResponseInterface, PayloadAwareInterface {}

src/JsonStream.php

@@ -20,43 +20,79 @@
 /**
  * Class JsonStream.
  *
- * Extends Nyholm's PSR-7 Stream implementation to provide JSON-specific stream functionality.
- * This class SHALL encapsulate a JSON-encoded payload within a PHP stream, while retaining the original
- * payload in a decoded form for convenient access.
+ * Provides a JSON-specific stream implementation, extending Nyholm's PSR-7 Stream.
+ * This class SHALL encapsulate a JSON-encoded payload within an in-memory PHP stream,
+ * while retaining the original decoded payload for convenient retrieval.
  *
- * Implementations MUST properly handle JSON encoding errors and enforce the prohibition of resource types
- * within JSON payloads.
+ * Implementations of this class MUST properly handle JSON encoding errors and SHALL explicitly
+ * prohibit the inclusion of resource types within the JSON payload.
  *
  * @package FastForward\Http\Message
  */
 final class JsonStream extends Stream implements JsonStreamInterface
 {
+    /**
+     * JSON encoding flags to be applied by default.
+     *
+     * The options JSON_THROW_ON_ERROR, JSON_UNESCAPED_SLASHES, and JSON_UNESCAPED_UNICODE
+     * SHALL be applied to enforce strict error handling and produce readable JSON output.
+     *
+     * @var int
+     */
     public const ENCODING_OPTIONS = JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE;
 
+    /**
+     * @var mixed The decoded payload provided to the stream. This MUST be JSON-encodable and MUST NOT contain resources.
+     */
+    private mixed $payload = [];
+
+    /**
+     * @var int The JSON encoding options to be applied. Defaults to self::ENCODING_OPTIONS.
+     */
+    private int $encodingOptions = self::ENCODING_OPTIONS;
+
     /**
      * Constructs a new JsonStream instance with the provided payload.
      *
-     * The payload SHALL be JSON-encoded and written to an in-memory PHP stream. The original payload is retained
-     * in decoded form for later retrieval via {@see getPayload()}.
+     * The payload SHALL be JSON-encoded and written to an in-memory stream. The original payload is retained
+     * in its decoded form for later access via getPayload().
      *
      * @param mixed $payload         The data to encode as JSON. MUST be JSON-encodable. Resources are explicitly prohibited.
-     * @param int   $encodingOptions Optional JSON encoding flags as defined by {@see json_encode()}. Defaults to 0.
+     * @param int   $encodingOptions Optional JSON encoding flags. If omitted, ENCODING_OPTIONS will be applied.
      */
-    public function __construct(
-        private mixed $payload = [],
-        private int $encodingOptions = self::ENCODING_OPTIONS
-    ) {
+    public function __construct(mixed $payload = [], int $encodingOptions = self::ENCODING_OPTIONS)
+    {
+        $this->payload         = $payload;
+        $this->encodingOptions = $encodingOptions;
+
         parent::__construct(fopen('php://temp', 'wb+'));
 
         $this->write($this->jsonEncode($this->payload, $this->encodingOptions));
         $this->rewind();
     }
 
+    /**
+     * Retrieves the decoded payload associated with the stream.
+     *
+     * This method SHALL return the original JSON-encodable payload provided during construction or via withPayload().
+     *
+     * @return mixed the decoded payload
+     */
     public function getPayload(): mixed
     {
         return $this->payload;
     }
 
+    /**
+     * Returns a new instance of the stream with the specified payload.
+     *
+     * This method MUST return a new JsonStream instance with the body replaced by a stream
+     * containing the JSON-encoded form of the new payload. The current instance SHALL remain unchanged.
+     *
+     * @param mixed $payload the new JSON-encodable payload
+     *
+     * @return self a new JsonStream instance containing the updated payload
+     */
     public function withPayload(mixed $payload): self
     {
         return new self($payload);
@@ -65,11 +101,11 @@ public function withPayload(mixed $payload): self
     /**
      * Encodes the given data as JSON, enforcing proper error handling.
      *
-     * If the provided data is a resource, this method SHALL throw an {@see \InvalidArgumentException} as resources
-     * cannot be represented in JSON format.
+     * If the provided data is a resource, this method SHALL throw an \InvalidArgumentException,
+     * as resource types are not supported by JSON.
      *
      * @param mixed $data            the data to encode as JSON
-     * @param int   $encodingOptions JSON encoding options, combined with JSON_THROW_ON_ERROR
+     * @param int   $encodingOptions JSON encoding options to apply. JSON_THROW_ON_ERROR will always be enforced.
      *
      * @return string the JSON-encoded string representation of the data
      *
@@ -79,10 +115,10 @@ public function withPayload(mixed $payload): self
     private function jsonEncode(mixed $data, int $encodingOptions): string
     {
         if (\is_resource($data)) {
-            throw new \InvalidArgumentException('Cannot JSON encode resources');
+            throw new \InvalidArgumentException('Cannot JSON encode resources.');
         }
 
-        // Clear json_last_error()
+        // Reset potential previous errors
         json_encode(null);
 
         return json_encode($data, $encodingOptions | JSON_THROW_ON_ERROR);

src/PayloadAwareInterface.php

@@ -18,35 +18,34 @@
 /**
  * Interface PayloadAwareInterface.
  *
- * Provide functionality for JSON payload handling.
+ * 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
  */
 interface PayloadAwareInterface
 {
     /**
-     * Retrieves the decoded JSON payload from the stream.
+     * Retrieves the payload contained within the object.
      *
-     * This method MUST return the decoded JSON payload as a native PHP type. The returned type MAY vary depending on
-     * the structure of the JSON content (e.g., array, object, int, float, string, bool, or null).
+     * This method MUST return the payload as originally provided or modified.
+     * The returned type MAY vary depending on the structure of the payload (e.g., array, object, scalar, or null).
      *
-     * @return mixed the decoded JSON payload, which MAY be of any type, including array, object, scalar, or null
+     * @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 provided payload encoded as JSON.
+     * Returns a new instance with the specified payload.
      *
-     * This method MUST NOT modify the existing instance; instead, it SHALL return a new instance with the updated
-     * JSON payload written to the underlying stream.
+     * 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.
      *
-     * The provided data MUST be JSON-encodable. If encoding fails, the method MAY throw an exception as defined
-     * by the implementation.
+     * @param mixed $payload the new payload to set in the instance
      *
-     * @param mixed $payload The data to encode as JSON and set as the stream's payload. This MAY be of any type
-     *                       supported by json_encode.
-     *
-     * @return self a new instance with the updated JSON payload
+     * @return self a new instance with the updated payload
      */
     public function withPayload(mixed $payload): self;
 }