Introduce ErrorHandler and StatelessApplication implementation with tests.

.github/workflows/build.yml

@@ -20,5 +20,7 @@ name: build
 jobs:
   phpunit:
     uses: php-forge/actions/.github/workflows/phpunit.yml@main
+    with:
+      extensions: mbstring, gd
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

composer-require-checker.json

@@ -0,0 +1,6 @@
+{
+    "symbol-whitelist": [
+        "uopz_redefine",
+        "YII_DEBUG"
+    ]
+}

composer.json

@@ -12,8 +12,10 @@
     "prefer-stable": true,
     "require": {
         "php": ">=8.1",
-        "psr/http-message": "^2.0",
+        "ext-mbstring": "*",
         "psr/http-factory": "^1.0",
+        "psr/http-message": "^2.0",
+        "psr/http-server-handler": "^1.0",
         "yiisoft/yii2": "^2.0.53|^22"
     },
     "require-dev": {
@@ -28,6 +30,9 @@
         "xepozz/internal-mocker": "^1.4",
         "yii2-extensions/phpstan": "^0.3"
     },
+    "suggest": {
+        "ext-uopz": "*"
+    },
     "autoload": {
         "psr-4": {
             "yii2\\extensions\\psrbridge\\": "src"

phpstan.neon

@@ -13,6 +13,9 @@ parameters:
 
     tmpDir: %currentWorkingDirectory%/runtime
 
+    yii2:
+        config_path: %currentWorkingDirectory%/tests/phpstan-config.php
+
     # Enable strict advanced checks
     checkImplicitMixed: true
     checkBenevolentUnionTypes: true

src/http/ErrorHandler.php

@@ -0,0 +1,190 @@
+<?php
+
+declare(strict_types=1);
+
+namespace yii2\extensions\psrbridge\http;
+
+use Throwable;
+use Yii;
+use yii\base\{InvalidRouteException, UserException};
+use yii\console\Exception;
+use yii\helpers\VarDumper;
+use yii\web\HttpException;
+
+use function array_diff_key;
+use function array_flip;
+use function htmlspecialchars;
+use function http_response_code;
+use function ini_set;
+
+/**
+ * Error handler extension with PSR-7 bridge support for Yii2 applications.
+ *
+ * Provides a drop-in replacement for {@see \yii\web\ErrorHandler} that integrates PSR-7 ResponseInterface handling,
+ * enabling seamless interoperability with PSR-7 compatible HTTP stacks and modern PHP runtimes.
+ *
+ * This class overrides exception handling to produce PSR-7 ResponseInterface objects, supporting custom error views,
+ * fallback rendering, and Yii2 error action integration.
+ *
+ * All exception handling is performed in a type-safe, immutable manner, ensuring compatibility with legacy Yii2
+ * workflows and modern middleware stacks.
+ *
+ * Key features.
+ * - Custom error view and error action support for HTML responses.
+ * - Exception-safe conversion to PSR-7 ResponseInterface objects.
+ * - Fallback rendering for nested exceptions and debug output.
+ * - Integration with Yii2 error action and view rendering.
+ * - Type-safe, immutable error handling for modern runtimes.
+ *
+ * @copyright Copyright (C) 2025 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
+final class ErrorHandler extends \yii\web\ErrorHandler
+{
+    /**
+     * Handles exceptions and produces a PSR-7 ResponseInterface object.
+     *
+     * Overrides the default Yii2 exception handling to generate a PSR-7 ResponseInterface instance, supporting custom
+     * error views, fallback rendering, and integration with Yii2 error actions.
+     *
+     * Ensures type-safe, immutable error handling for modern runtimes.
+     *
+     * This method guarantees that all exceptions are converted to PSR-7 ResponseInterface, maintaining compatibility
+     * with both legacy Yii2 workflows and modern middleware stacks.
+     *
+     * @param Throwable $exception Exception to handle and convert to a PSR-7 ResponseInterface object.
+     *
+     * @return Response PSR-7 ResponseInterface representing the handled exception.
+     */
+    public function handleException($exception): Response
+    {
+        $this->exception = $exception;
+
+        $this->unregister();
+
+        if (PHP_SAPI !== 'cli') {
+            $statusCode = 500;
+
+            if ($exception instanceof HttpException) {
+                $statusCode = $exception->statusCode;
+            }
+
+            http_response_code($statusCode);
+        }
+
+        try {
+            $this->logException($exception);
+
+            if ($this->discardExistingOutput) {
+                $this->clearOutput();
+            }
+
+            $response = $this->renderException($exception);
+        } catch (Throwable $e) {
+            return $this->handleFallbackExceptionMessage($e, $exception);
+        }
+
+        $this->exception = null;
+
+        return $response;
+    }
+
+    /**
+     * Handles fallback exception rendering when an error occurs during exception processing.
+     *
+     * Produces a {@see Response} object with a generic error message and, in debug mode, includes detailed exception
+     * information and a sanitized snapshot of server variables, excluding sensitive keys.
+     *
+     * This method ensures that nested or secondary exceptions do not expose sensitive data and provides a minimal
+     * diagnostic output for debugging purposes.
+     *
+     * @param Throwable $exception Exception thrown during error handling.
+     * @param Throwable $previousException Original exception that triggered error handling.
+     *
+     * @return Response Object containing the fallback error message and debug output if enabled.
+     */
+    protected function handleFallbackExceptionMessage($exception, $previousException): Response
+    {
+        $response = new Response();
+
+        $msg = "An Error occurred while handling another error:\n";
+
+        $msg .= $exception;
+
+        $msg .= "\nPrevious exception:\n";
+
+        $msg .= $previousException;
+
+        $response->data = 'An internal server error occurred.';
+
+        if (YII_DEBUG) {
+            $response->data = '<pre>' . htmlspecialchars($msg, ENT_QUOTES, Yii::$app->charset) . '</pre>';
+            $safeServerVars = array_diff_key(
+                $_SERVER,
+                array_flip(
+                    [
+                        'API_KEY',
+                        'AUTH_TOKEN',
+                        'DB_PASSWORD',
+                        'SECRET_KEY',
+                    ],
+                ),
+            );
+            $response->data .= "\n\$_SERVER = " . VarDumper::export($safeServerVars);
+        }
+
+        return $response;
+    }
+
+    /**
+     * Renders the exception and produces a {@see Response} object with appropriate error content.
+     *
+     * Handles exception rendering for HTML, raw, and array formats, supporting custom error views and error actions.
+     *
+     * This method ensures type-safe, immutable error handling and maintains compatibility with Yii2 error actions and
+     * view rendering.
+     *
+     * @param Throwable $exception Exception to render and convert to a {@see Response} object.
+     *
+     * @throws Exception if an error occurs during error action execution.
+     * @throws InvalidRouteException if the error action route is invalid or cannot be resolved.
+     *
+     * @return Response Object containing the rendered exception output.
+     */
+    protected function renderException($exception): Response
+    {
+        $response = new Response();
+
+        $response->setStatusCodeByException($exception);
+
+        $useErrorView = $response->format === Response::FORMAT_HTML && (!YII_DEBUG || $exception instanceof UserException);
+
+        if ($useErrorView && $this->errorAction !== null) {
+            $result = Yii::$app->runAction($this->errorAction);
+
+            if ($result instanceof Response) {
+                $response = $result;
+            } else {
+                $response->data = $result;
+            }
+        } elseif ($response->format === Response::FORMAT_HTML) {
+            if ($this->shouldRenderSimpleHtml()) {
+                $response->data = '<pre>' . $this->htmlEncode(self::convertExceptionToString($exception)) . '</pre>';
+            } else {
+                if (YII_DEBUG) {
+                    ini_set('display_errors', '1');
+                }
+
+                $file = $useErrorView ? $this->errorView : $this->exceptionView;
+
+                $response->data = $this->renderFile($file, ['exception' => $exception]);
+            }
+        } elseif ($response->format === Response::FORMAT_RAW) {
+            $response->data = self::convertExceptionToString($exception);
+        } else {
+            $response->data = $this->convertExceptionToArray($exception);
+        }
+
+        return $response;
+    }
+}

src/http/Request.php

@@ -10,7 +10,14 @@
 use yii2\extensions\psrbridge\adapter\ServerRequestAdapter;
 use yii2\extensions\psrbridge\exception\Message;
 
+use function base64_decode;
+use function count;
+use function explode;
 use function is_array;
+use function is_string;
+use function mb_check_encoding;
+use function mb_substr;
+use function strncasecmp;
 
 /**
  * HTTP Request extension with PSR-7 bridge and worker mode support.
@@ -43,6 +50,12 @@
  */
 final class Request extends \yii\web\Request
 {
+    /**
+     * @var string A secret key used for cookie validation. This property must be set if {@see enableCookieValidation}
+     * is 'true'.
+     */
+    public $cookieValidationKey = '';
+
     /**
      * Whether the request is in worker mode.
      */
@@ -56,6 +69,75 @@ final class Request extends \yii\web\Request
      */
     private ServerRequestAdapter|null $adapter = null;
 
+    /**
+     * Retrieves HTTP Basic authentication credentials from the current request.
+     *
+     * Returns an array containing the username and password sent via HTTP authentication, supporting both standard PHP
+     * SAPI variables and the 'Authorization' header for environments where credentials are not passed directly.
+     *
+     * The method first checks for credentials in the PHP_AUTH_USER and PHP_AUTH_PW server variables. If not present, it
+     * attempts to extract and decode credentials from the 'Authorization' header, handling Apache php-cgi scenarios and
+     * validating the decoded data for UTF-8 encoding and proper format.
+     *
+     * Usage example:
+     * ```php
+     * [$username, $password] = $request->getAuthCredentials();
+     * ```
+     *
+     * @return array Contains exactly two elements.
+     *   - 0: username sent via HTTP authentication, `null` if the username is not given.
+     *   - 1: password sent via HTTP authentication, `null` if the password is not given.
+     *
+     * @phpstan-return array{0: string|null, 1: string|null}
+     */
+    public function getAuthCredentials(): array
+    {
+        $username = isset($_SERVER['PHP_AUTH_USER']) && is_string($_SERVER['PHP_AUTH_USER'])
+            ? $_SERVER['PHP_AUTH_USER']
+            : null;
+        $password = isset($_SERVER['PHP_AUTH_PW']) && is_string($_SERVER['PHP_AUTH_PW'])
+            ? $_SERVER['PHP_AUTH_PW']
+            : null;
+
+        if ($username !== null || $password !== null) {
+            return [$username, $password];
+        }
+
+        /**
+         * Apache with php-cgi does not pass HTTP Basic authentication to PHP by default.
+         * To make it work, add one of the following lines to to your .htaccess file:
+         *
+         * SetEnvIf Authorization .+ HTTP_AUTHORIZATION=$0
+         * --OR--
+         * RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
+         */
+        $authToken = $this->getHeaders()->get('Authorization');
+
+        /** @phpstan-ignore-next-line */
+        if ($authToken !== null && strncasecmp($authToken, 'basic', 5) === 0) {
+            $encoded = mb_substr($authToken, 6);
+            $decoded = base64_decode($encoded, true); // strict mode
+
+            // validate decoded data
+            if ($decoded === false || mb_check_encoding($decoded, 'UTF-8') === false) {
+                return [null, null]; // return null for malformed credentials
+            }
+
+            $parts = explode(':', $decoded, 2);
+
+            if (count($parts) < 2) {
+                return [$parts[0] === '' ? null : $parts[0], null];
+            }
+
+            return [
+                $parts[0] === '' ? null : $parts[0],
+                (isset($parts[1]) && $parts[1] !== '') ? $parts[1] : null,
+            ];
+        }
+
+        return [null, null];
+    }
+
     /**
      * Retrieves the request body parameters, excluding the HTTP method override parameter if present.
      *