From 48043f6557048001ed02633f98f91b1adafff510 Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Tue, 22 Jul 2025 10:33:32 -0400 Subject: [PATCH] refactor(request): Update documentation to clarify PSR-7 `ServerRequestInterface` class references and improve consistency across the `Request` and `SapiEmitter` classes. --- src/adapter/ServerRequestAdapter.php | 66 ++++++++++++++-------------- src/emitter/SapiEmitter.php | 18 ++++---- src/http/Request.php | 64 +++++++++++++-------------- 3 files changed, 75 insertions(+), 73 deletions(-) diff --git a/src/adapter/ServerRequestAdapter.php b/src/adapter/ServerRequestAdapter.php index 449f4533..62b53c33 100644 --- a/src/adapter/ServerRequestAdapter.php +++ b/src/adapter/ServerRequestAdapter.php @@ -18,10 +18,10 @@ use function strtoupper; /** - * Adapter for PSR-7 ServerRequest to Yii2 Request component. + * Adapter for PSR-7 ServerRequestInterface to Yii2 Request component. * - * Provides a bridge between PSR-7 ServerRequestInterface and Yii2 Request component, enabling seamless integration - * of PSR-7 compatible HTTP stacks with Yii2 applications. + * Provides a bridge between PSR-7 {@see ServerRequestInterface} and Yii2 {@see Request} component, enabling seamless + * integration of PSR-7 compatible HTTP stacks with Yii2 Application. * * This adapter exposes methods to access request data such as body parameters, cookies, headers, HTTP method, query * parameters, uploaded files, and URL information in a format compatible with Yii2 expectations. @@ -32,14 +32,14 @@ * All returned data is immutable and designed for safe, read-only access. * * Key features. - * - Cookie extraction with optional Yii2-style validation. + * - Cookie extraction with optional Yii2 style validation. * - Fluent, exception-safe API for request inspection. * - HTTP method override support via body and headers. * - Immutable, type-safe access to request data and metadata. * - PSR-7 to Yii2 Request component for seamless interoperability. * - Worker mode compatibility for modern PHP runtimes. * - * @see ServerRequestInterface for PSR-7 request contract. + * @see ServerRequestInterface for PSR-7 ServerRequestInterface contract. * * @copyright Copyright (C) 2025 Terabytesoftw. * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. @@ -51,20 +51,20 @@ final class ServerRequestAdapter * * @param ServerRequestInterface $psrRequest PSR-7 ServerRequestInterface instance to adapt. */ - public function __construct(public ServerRequestInterface $psrRequest) {} + public function __construct(public readonly ServerRequestInterface $psrRequest) {} /** * Retrieves the request body parameters, excluding the HTTP method override parameter if present. * - * Returns the parsed body parameters from the PSR-7 request, removing the specified method override parameter (such - * as '_method') if it exists. + * Returns the parsed body parameters from the PSR-7 ServerRequestInterface, removing the specified method override + * parameter (such as '_method') if it exists. * * This ensures that the method override value does not appear in the Yii2 Controller action parameters, maintaining * compatibility with Yii2 Request component logic. * * - If the parsed body is not an array or the method parameter is not present, the original parsed body is * returned. - * - If the parsed body is null, an empty array is returned for consistency. + * - If the parsed body is `null`, an empty array is returned for consistency. * * @param string $methodParam Name of the HTTP method override parameter to exclude (for example, '_method'). * @@ -108,7 +108,7 @@ public function getBodyParams(string $methodParam): array|object * * @throws InvalidConfigException if the configuration is invalid or incomplete. * - * @return array Array of {@see Cookie} objects extracted from the PSR-7 request. + * @return array Array of {@see Cookie} objects extracted from the PSR-7 ServerRequestInterface. * * @phpstan-return array * @@ -125,12 +125,12 @@ public function getCookies(bool $enableValidation, string $validationKey = ''): } /** - * Retrieves all HTTP headers from the PSR-7 request as a Yii2 {@see HeaderCollection} instance. + * Retrieves all HTTP headers from the PSR-7 ServerRequestInterface as a Yii2 {@see HeaderCollection} instance. * - * Iterates over each header in the PSR-7 ServerRequest and adds it to a new {@see HeaderCollection} instance, - * concatenating multiple values with a comma and space, as expected by Yii2. + * Iterates over each header in the PSR-7 ServerRequestInterface and adds it to a new {@see HeaderCollection} + * instance, concatenating multiple values with a comma and space, as expected by Yii2. * - * @return HeaderCollection Collection of HTTP headers from the PSR-7 request. + * @return HeaderCollection Collection of HTTP headers from the PSR-7 ServerRequestInterface. * * Usage example: * ```php @@ -156,7 +156,7 @@ public function getHeaders(): HeaderCollection * 'X-Http-Method-Override' header. * * - If a valid override is found and is not one of 'GET', 'HEAD', or 'OPTIONS', it is returned in uppercase. - * - Otherwise, the original method from the PSR-7 request is returned. + * - Otherwise, the original method from the PSR-7 ServerRequestInterface is returned. * * This method enables support for HTTP method spoofing in environments where certain HTTP verbs are not natively * supported by clients or proxies, ensuring compatibility with RESTful routing and Yii2 Controller actions. @@ -200,7 +200,7 @@ public function getMethod(string $methodParam = '_method'): string } /** - * Retrieves the parsed body parameters from the PSR-7 request. + * Retrieves the parsed body parameters from the PSR-7 ServerRequestInterface. * * @return array|object|null Parsed body parameters as `array`, `object`, or `null` if not present. * @@ -217,7 +217,7 @@ public function getParsedBody(): array|object|null } /** - * Retrieves query parameters from the PSR-7 request. + * Retrieves query parameters from the PSR-7 ServerRequestInterface. * * Returns the query parameters as an associative array, providing direct access to all values present in the * request URI. @@ -237,7 +237,7 @@ public function getQueryParams(): array } /** - * Retrieves the raw query string from the PSR-7 request URI. + * Retrieves the raw query string from the PSR-7 ServerRequestInterface URI. * * @return string Raw query string from the request URI, or an empty string if not present. * @@ -252,7 +252,7 @@ public function getQueryString(): string } /** - * Retrieves the raw body content from the PSR-7 request stream. + * Retrieves the raw body content from the PSR-7 ServerRequestInterface stream. * * Returns the entire contents of the underlying stream as a string, rewinding first if the stream is seekable. * @@ -261,7 +261,7 @@ public function getQueryString(): string * * The stream is rewound before reading (if seekable) to ensure the full content is returned from the beginning. * - * @return string Raw body content from the PSR-7 request stream. + * @return string Raw body content from the PSR-7 ServerRequestInterface stream. * * Usage example: * ```php @@ -282,7 +282,7 @@ public function getRawBody(): string /** * Retrieves the script URL from server parameters, supporting both SAPI and worker environments. * - * Returns the value of 'SCRIPT_NAME' from server parameters for traditional SAPI-based PSR-7 applications. + * Returns the value of 'SCRIPT_NAME' from server parameters for traditional SAPI-based PSR-7 Application. * * For worker-based environments (such as RoadRunner, FrankenPHP), returns an empty string to prevent URL * duplication, as routing is handled internally and no script file exists. @@ -303,25 +303,25 @@ public function getScriptUrl(bool $workerMode): string { $serverParams = $this->psrRequest->getServerParams(); - // for traditional 'PSR-7' apps where 'SCRIPT_NAME' is available + // for traditional PSR-7 apps where 'SCRIPT_NAME' is available if ($workerMode === false && isset($serverParams['SCRIPT_NAME']) && is_string($serverParams['SCRIPT_NAME'])) { return $serverParams['SCRIPT_NAME']; } - // for 'PSR-7' workers (RoadRunner, FrankenPHP, etc.) where no script file exists + // for PSR-7 workers (RoadRunner, FrankenPHP, etc.) where no script file exists // return empty to prevent URL duplication as routing is handled internally return ''; } /** - * Retrieves uploaded files from the PSR-7 request. + * Retrieves uploaded files from the PSR-7 ServerRequestInterface. * - * Returns the uploaded files as provided by the underlying PSR-7 ServerRequest instance. + * Returns the uploaded files as provided by the underlying PSR-7 ServerRequestInterface instance. * * This method exposes the raw uploaded files array, enabling direct access to all files sent with the request * in a format compatible with PSR-7 expectations. * - * @return array Uploaded files from the PSR-7 request. + * @return array Uploaded files from the PSR-7 ServerRequestInterface. * * @phpstan-return array * @@ -365,16 +365,16 @@ public function getUrl(): string } /** - * Extracts cookies from the PSR-7 request without validation. + * Extracts cookies from the PSR-7 ServerRequestInterface without validation. * - * Iterates over the cookie parameters provided by the PSR-7 ServerRequest and creates a {@see Cookie} instance for + * Iterates over the cookie parameters provided by the PSR-7 ServerRequestInterface and creates a {@see Cookie} instance for * each non-empty value. * * This method returns all cookies as-is, without applying Yii2 style validation or decoding. * * It is intended for use in cases where cookie integrity is not enforced by a validation key. * - * @return array Array of {@see Cookie} objects extracted from the PSR-7 request. + * @return array Array of {@see Cookie} objects extracted from the PSR-7 ServerRequestInterface. * * @phpstan-return array */ @@ -399,15 +399,15 @@ private function getSimpleCookies(): array } /** - * Extracts and validates cookies from the PSR-7 request using Yii2 style validation. + * Extracts and validates cookies from the PSR-7 ServerRequestInterface using Yii2 style validation. * - * Iterates over the cookie parameters provided by the PSR-7 ServerRequest and validates each value using the + * Iterates over the cookie parameters provided by the PSR-7 ServerRequestInterface and validates each value using the * specified validation key. * * Only cookies that pass validation and decoding are included in the result. * - * This ensures that only cookies with integrity verified by Yii2's security component are returned, supporting - * secure cookie extraction for Yii2 applications. + * This ensures that only cookies with integrity verified by Yii2 Security component are returned, supporting + * secure cookie extraction for Yii2 Application. * * @param string $validationKey Validation key used for Yii2 Cookie validation. * diff --git a/src/emitter/SapiEmitter.php b/src/emitter/SapiEmitter.php index d4a29faf..c4a803fc 100644 --- a/src/emitter/SapiEmitter.php +++ b/src/emitter/SapiEmitter.php @@ -8,6 +8,7 @@ use yii\base\InvalidArgumentException; use yii2\extensions\psrbridge\exception\{HeadersAlreadySentException, Message, OutputAlreadySentException}; +use function array_map; use function implode; use function ob_get_length; use function ob_get_level; @@ -18,11 +19,12 @@ use function ucwords; /** - * SAPI (Server API) Response Emitter. + * SAPI (Server API) ResponseInterface Emitter. * - * This class is responsible for emitting PSR-7 Response objects to the output buffer using PHP's Server API. It handles - * the emission of headers, status line, and response body while supporting features like content range and buffered - * output. + * This class is responsible for emitting PSR-7 ResponseInterface objects to the output buffer using PHP's Server API. + * + * It handles the emission of headers, status line, and response body while supporting features like content range and + * buffered output. * * According to 'HTTP/1.1' specifications, certain status codes MUST NOT include a message body: * - '1xx' (Informational): '100' Continue, '101' Switching Protocols, '102' Processing, '103' Early Hints. @@ -64,7 +66,7 @@ public function __construct(private readonly int|null $bufferLength = null) * ('100' - '103', '204', '205', '304') MUSTN'T include a message body. For these status codes, the body will not * be emitted even if present in the response object. {@see HttpNoBodyStatus} for the complete list. * - * @param ResponseInterface $response PSR-7 response instance. + * @param ResponseInterface $response PSR-7 ResponseInterface instance. * @param bool $body Whether to emit the response with body (default: `true`). * * @throws HeadersAlreadySentException if HTTP headers have already been sent to the client. @@ -97,7 +99,7 @@ public function emit(ResponseInterface $response, bool $body = true): void * Handles the emission of the response body, supporting both buffered and unbuffered output, also supports content * range responses for partial content delivery. * - * @param ResponseInterface $response PSR-7 response instance. + * @param ResponseInterface $response PSR-7 ResponseInterface instance. */ private function emitBody(ResponseInterface $response): void { @@ -165,7 +167,7 @@ private function emitBodyRange(StreamInterface $body, int $first, int $last): vo * Iterates through the response headers and emits each one. Special handling is provided for the 'Set-Cookie' * header to ensure multiple cookies are handled correctly. * - * @param ResponseInterface $response PSR-7 response instance. + * @param ResponseInterface $response PSR-7 ResponseInterface instance. */ private function emitHeaders(ResponseInterface $response): void { @@ -187,7 +189,7 @@ private function emitHeaders(ResponseInterface $response): void * * Emits the HTTP protocol version, status code, and reason phrase. * - * @param ResponseInterface $response PSR-7 response instance. + * @param ResponseInterface $response PSR-7 ResponseInterface instance. */ private function emitStatusLine(ResponseInterface $response): void { diff --git a/src/http/Request.php b/src/http/Request.php index adc8c7b5..74a51eb7 100644 --- a/src/http/Request.php +++ b/src/http/Request.php @@ -15,25 +15,25 @@ /** * HTTP Request extension with PSR-7 bridge and worker mode support. * - * Provides a drop-in replacement for {@see \yii\web\Request} that integrates PSR-7 ServerRequest handling, enabling - * seamless interoperability with PSR-7 compatible HTTP stacks and modern PHP runtimes. + * Provides a drop-in replacement for {@see \yii\web\Request} that integrates PSR-7 ServerRequestInterface handling, + * enabling seamless interoperability with PSR-7 compatible HTTP stacks and modern PHP runtimes. * * This class delegates request data access (body, headers, cookies, files, etc.) to a {@see ServerRequestAdapter} - * when a PSR-7 request is set, supporting both traditional SAPI and worker-based environments (such as RoadRunner, - * FrankenPHP, or similar). + * when a PSR-7 ServerRequestInterface is set, supporting both traditional SAPI and worker-based environments (such as + * RoadRunner, FrankenPHP, or similar). * * All methods transparently fall back to the parent implementation if no PSR-7 adapter is present, ensuring * compatibility with legacy Yii2 workflows. * - * The class also provides conversion utilities for PSR-7 uploaded files and exposes the underlying PSR-7 request for - * advanced use cases. + * The class also provides conversion utilities for PSR-7 {@see UploadedFileInterface} and exposes the underlying PSR-7 + * ServerRequestInterface for advanced use cases. * * Key features: * - Automatic fallback to Yii2 parent methods when no adapter is set. - * - Conversion utilities for PSR-7 uploaded files to Yii2 format. - * - Full compatibility with Yii2's cookie validation and CSRF protection. + * - Conversion utilities for PSR-7 UploadedFileInterface to Yii2 format. + * - Full compatibility with Yii2 Cookie validation and CSRF protection. * - Immutable, type-safe access to request data (body, headers, cookies, files, query, etc.). - * - PSR-7 ServerRequest integration via {@see setPsr7Request()} and {@see getPsr7Request()}. + * - PSR-7 ServerRequestAdapter integration via {@see setPsr7Request()} and {@see getPsr7Request()}. * - Worker mode support for modern runtimes (see {@see $workerMode}). * * @see ServerRequestAdapter for PSR-7 to Yii2 Request adapter. @@ -49,18 +49,18 @@ final class Request extends \yii\web\Request public bool $workerMode = true; /** - * PSR-7 request adapter for bridging PSR-7 ServerRequest with Yii2 Request component. + * PSR-7 ServerRequestAdapter for bridging PSR-7 ServerRequestInterface with Yii2 Request component. * - * Adapter allows the Request class to access PSR-7 request data while maintaining compatibility with Yii2 Request - * component. + * Adapter allows the Request class to access PSR-7 ServerRequestInterface data while maintaining compatibility with + * Yii2 Request component. */ private ServerRequestAdapter|null $adapter = null; /** * Retrieves the request body parameters, excluding the HTTP method override parameter if present. * - * Returns the parsed body parameters from the PSR-7 request, removing the specified method override parameter (such - * as '_method') if it exists. + * Returns the parsed body parameters from the PSR-7 ServerRequestInterface, removing the specified method override + * parameter (such as '_method') if it exists. * * If the PSR-7 adapter is not set, it falls back to the parent implementation. * @@ -90,8 +90,8 @@ public function getBodyParams(): array|object /** * Retrieves cookies from the current request, supporting PSR-7 and Yii2 validation. * - * Returns a {@see CookieCollection} containing cookies extracted from the PSR-7 request if the adapter is set, - * applying Yii2 style validation when enabled. + * Returns a {@see CookieCollection} containing cookies extracted from the PSR-7 ServerRequestInterface if the + * adapter is set, applying Yii2 style validation when enabled. * * If no adapter is present, falls back to the parent implementation. * @@ -144,8 +144,8 @@ public function getCsrfTokenFromHeader(): string|null /** * Retrieves HTTP headers from the current request, supporting PSR-7 and Yii2 fallback. * - * Returns a {@see HeaderCollection} containing all HTTP headers extracted from the PSR-7 request if the adapter is - * set. + * Returns a {@see HeaderCollection} containing all HTTP headers extracted from the PSR-7 ServerRequestInterface if + * the adapter is set. * * Applies internal header filtering for compatibility with Yii2 expectations. * @@ -229,7 +229,7 @@ public function getParsedBody(): array|object|null } /** - * Retrieves the underlying PSR-7 ServerRequest instance from the adapter. + * Retrieves the underlying PSR-7 ServerRequestInterface instance from the adapter. * * Returns the PSR-7 {@see ServerRequestInterface} associated with this request via the internal adapter. * @@ -241,7 +241,7 @@ public function getParsedBody(): array|object|null * * @throws InvalidConfigException if the configuration is invalid or incomplete. * - * @return ServerRequestInterface PSR-7 ServerRequest instance from the adapter. + * @return ServerRequestInterface PSR-7 ServerRequestInterface instance from the adapter. * * Usage example: * ```php @@ -419,10 +419,10 @@ public function getUrl(): string } /** - * Reset the PSR-7 request adapter to its initial state. + * Reset the PSR-7 ServerRequestInterface adapter to its initial state. * - * Sets the internal adapter property to `null`, removing any previously set PSR-7 ServerRequest adapter and - * restoring the default behavior of the request component. + * Sets the internal adapter property to `null`, removing any previously set PSR-7 ServerRequestInterface adapter + * and restoring the default behavior of the request component. * * This method is used to clear the PSR-7 bridge in worker mode, ensuring that subsequent request operations fall * back to the parent Yii2 implementation. @@ -438,7 +438,7 @@ public function reset(): void } /** - * Sets the PSR-7 ServerRequest instance for the current request. + * Sets the PSR-7 ServerRequestInterface instance for the current request. * * Assigns a new {@see ServerRequestAdapter} wrapping the provided PSR-7 {@see ServerRequestInterface} to enable * PSR-7 interoperability for the Yii2 Request component. @@ -446,7 +446,7 @@ public function reset(): void * This method is used to bridge PSR-7 compatible HTTP stacks with Yii2, allowing request data to be accessed via * the adapter. * - * Once set, all request operations will use the PSR-7 request until {@see reset()} is called. + * Once set, all request operations will use the PSR-7 ServerRequestInterface until {@see reset()} is called. * * @param ServerRequestInterface $request PSR-7 ServerRequestInterface instance to bridge. * @@ -462,7 +462,7 @@ public function setPsr7Request(ServerRequestInterface $request): void } /** - * Converts an array of PSR-7 uploaded files to Yii2 UploadedFile instances recursively. + * Converts an array of PSR-7 UploadedFileInterface to Yii2 UploadedFile instances recursively. * * Iterates through the provided array of uploaded files, converting each {@see UploadedFileInterface} instance * to a Yii2 {@see UploadedFile} object. @@ -496,17 +496,17 @@ private function convertPsr7ToUploadedFiles(array $uploadedFiles): array } /** - * Creates a new {@see UploadedFile} instance from a PSR-7 uploaded file. + * Creates a new {@see UploadedFile} instance from a PSR-7 UploadedFileInterface. * * Converts a {@see UploadedFileInterface} object to a Yii2 {@see UploadedFile} instance by extracting the error - * code, client filename, file size, temporary file path, and media type from the PSR-7 file. + * code, client filename, file size, temporary file path, and media type from the PSR-7 UploadedFileInterface. * - * This method is used internally to bridge PSR-7 uploaded files with Yii2's file upload handling, ensuring - * compatibility between modern HTTP stacks and Yii2's expected file structure. + * This method is used internally to bridge PSR-7 UploadedFileInterface with Yii2 file upload handling, ensuring + * compatibility between modern HTTP stacks and Yii2 expected file structure. * - * @param UploadedFileInterface $psrFile PSR-7 uploaded file instance to convert. + * @param UploadedFileInterface $psrFile PSR-7 UploadedFileInterface instance to convert. * - * @return UploadedFile Yii2 UploadedFile instance created from the PSR-7 file. + * @return UploadedFile Yii2 UploadedFile instance created from the PSR-7 UploadedFileInterface. */ private function createUploadedFile(UploadedFileInterface $psrFile): UploadedFile {