Download the PHP package phpsoftbox/application without Composer

Application

Минимальное приложение для работы с PSR-15 пайплайном.

Окружение приложения

Приложение определяет собственный string-backed enum и реализует framework-контракт:

ApplicationEnvironment также принимает EnvironmentPolicyInterface и нормализованный запрос debug. Без policy методы isDebug() и isProductionLike() возвращают false.

Быстрый старт

$app->run($request) обрабатывает запрос и отправляет ответ через SapiEmitter (или переданный эмиттер). Для HEAD ответ формирует GET-маршрут, заголовки отправляются как у GET, тело — нет.

Настройка формата ошибок (Deciders)

ContentNegotiationExceptionHandler поддерживает реестр deciders для выбора формата ответа на ошибку. Decider возвращает ExceptionFormat::JSON, ExceptionFormat::HTML или null (тогда срабатывает стандартная логика по Accept и X-Requested-With).

Репортинг ошибок в ErrorHub

Если нужно добавить теги на уровне конкретного исключения:

Обработанные (soft) исключения

SoftExceptionReporter используется, когда вызывающий код осознанно выбирает fallback, но исключение нельзя скрывать из logger/ErrorHub:

В тестовом bootstrap можно зарегистрировать SoftExceptionMode::Throw. Тогда report() бросает тот же экземпляр исключения и тест не пропускает fallback-ветку незаметно. В режиме Report ошибка любого конкретного reporter-а не меняет основной control flow.

ExceptionReporterInterface не требует HTTP request. Для необработанных HTTP-исключений DefaultExceptionHandler добавляет request через ExceptionReportContext::fromRequest(); CLI, queue и интеграции передают только доступный им контекст.

RouterFactory + RouteCache

AppFactory

Регистрация middleware

Middleware из контейнера создаются лениво, в момент вызова: ошибка создания (например, отсутствующая зависимость) проходит через ErrorHandlerMiddleware, если он стоит выше в стеке.

RequestSizeLimitMiddleware проверяет Content-Length, а без него (chunked) — фактический размер тела: читает его не дальше лимита и возвращает поток в начало.

CorsMiddleware не допускает allowedOrigins: ['*'] вместе с allowCredentials: true — это исключение конфигурации: с credentials разрешённые origin нужно перечислить явно.

Обработчик ошибок с репортерами

DefaultExceptionHandler сообщает исключение репортерам (LoggerExceptionReporter, ErrorHubExceptionReporter и свои) и передаёт ответ обработчику по умолчанию. Сессия необязательна: без неё (API-приложение) ошибки валидации и CSRF отдаются обработчиком по умолчанию, а не редиректом «назад». CSRF-ошибка для JSON-клиента — ответ 419.

Группы middleware

Регистрация роутов через Application

Методы проксируются в RouteCollector, если приложение создано с Router.

Middleware для контроллеров

Рекомендуемый путь привязки Middleware — регистрация через Router на маршруты/группы; контроллеры/экшены используйте точечно.

Группы middleware для маршрутов

Ответы

В приложении доступны готовые ответы:

• JsonResponse
• HtmlResponse
• XmlResponse
• TextResponse

Пример:

Ошибки роутера

InvalidRouteParameterException (например, когда параметр не проходит валидацию) возвращает 404 Not Found в любом режиме: текст исключения описывает правила маршрута и в ответ не попадает.

Машиночитаемые JSON-ошибки

JsonExceptionHandler всегда добавляет стабильное поле code. Для предметных публичных ошибок используйте CodedHttpException либо преобразуйте исходное исключение через ExceptionMapperRegistry:

details считаются публичными данными и попадают в production response. debugMessage, исходное exception message и stack trace доступны только при включённом debug-режиме. Это изменение формата: потребителям JSON-ошибок нужно учесть новое обязательное поле code.

Доверенные прокси

TrustedProxyMiddleware ставится первым в стеке. Заголовки X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host и X-Forwarded-Port учитываются, только если REMOTE_ADDR входит в список доверенных прокси (IP или CIDR, IPv4 и IPv6). Тогда middleware:

• подставляет в REMOTE_ADDR IP клиента — первый справа адрес X-Forwarded-For, который сам не доверенный прокси (левые адреса цепочки клиент может подделать); адрес прокси — в атрибуте proxy_addr;
• подставляет в URI запроса схему, host и порт от прокси.

Остальной код (Auth, Session, Router, rate limiter) читает только REMOTE_ADDR и URI и сам заголовки X-Forwarded-* не учитывает. Без списка прокси заголовки игнорируются.

В AppBackend список задаётся переменной APP_TRUSTED_PROXIES (через запятую).

Rate limit middleware

Middleware принимает проектный key resolver, нормализует результат через RateLimitKeyNormalizerInterface и добавляет namespace. В production передавайте атомарный limiter, например RedisRateLimiter из phpsoftbox/rate-limiter:

X-RateLimit-Reset теперь является абсолютным Unix timestamp, а Retry-After — относительным числом секунд. Сырые credentials не следует возвращать из key resolver.

Авторизация приватных каналов Broadcaster

Обычно требуется эндпоинт /broadcast/auth, который выдаёт auth для приватных каналов. Пример с PushrChannelAuth:

socket_id клиент получает из события connection после подключения к WebSocket.