PSR-7 — API
HTTP-объекты
Заголовок раздела «HTTP-объекты»Все классы ниже находятся в localzet\PSR7; типы HTTP-интерфейсов — в Psr\Http\Message.
| Класс / конструктор | Назначение |
|---|---|
Request($method, $uri, $headers = [], $body = null, $version = '1.1') | Исходящий HTTP-запрос; URI — строка либо UriInterface. |
Response($status = 200, $headers = [], $body = null, $version = '1.1', $reason = null) | HTTP-ответ. |
ServerRequest(string $httpBuffer) | Входящий запрос, разобранный через Localzet Server. |
Uri(string $uri = '') | URI с компонентами scheme/user info/host/port/path/query/fragment. |
UploadedFile($streamOrFile, $size, $errorStatus, $clientFilename = null, $clientMediaType = null) | Загруженный файл из пути, resource либо StreamInterface. |
Методы get* читают состояние; семантику with* смотрите ниже. Конструктор ServerRequest отличается от конструктора обычного Request и не предназначен для передачи готового PSR request.
Изменение состояния
Заголовок раздела «Изменение состояния»| Операция | Возвращает |
|---|---|
Message withHeader, withAddedHeader, withoutHeader, withProtocolVersion, withBody | Тот же объект с изменённым состоянием. |
Дополнительные withHeaders, setHeaders | Тот же объект; значения существующих заголовков объединяются. |
Request withMethod, withRequestTarget, withUri | Тот же объект. |
Response withStatus | Копию response с новым кодом и reason phrase. |
Uri withScheme/withUserInfo/withHost/withPort/withPath/withQuery/withFragment | Изменённую копию; при неизменившемся значении может вернуться исходный объект. |
ServerRequest withUploadedFiles/withCookieParams/withQueryParams/withParsedBody/withAttribute | Копию request. |
ServerRequest withoutAttribute | Копию при удалении; исходный объект, если атрибута не было. |
Это важное ограничение интеграции с middleware, ожидающим неизменяемые PSR-сообщения. Методы этого пакета следует проверять по конкретному классу; единое правило для всех with* здесь не действует.
Request::withUri($uri, $preserveHost = false) обновляет Host, если новый URI содержит hostname и сохранение Host не запрошено. В отличие от более сложной политики некоторых PSR-реализаций, true здесь просто не вызывает обновление Host.
| Тип | Когда использовать | Ограничение |
|---|---|---|
Stream($resource, $options = []) | Обычный PHP stream resource | Возможности зависят от underlying resource. |
LazyOpenStream($filename, $mode) | Отложенное открытие файла | Ошибка открытия возникнет при первом реальном обращении. |
PumpStream($callback, $options = []) | Получение данных по частям от callback | Не поддерживает seek и запись. Callback завершает поток через false или null. |
BufferStream($hwm = 16384) | Буфер с потреблением при чтении | High-water mark не ограничивает фактически сохранённые байты. |
AppendStream($streams = []) | Последовательное чтение нескольких потоков | Только чтение; seek зависит от составляющих потоков. |
LimitStream($stream, $limit = -1, $offset = 0) | Читать участок исходного потока | -1 означает отсутствие лимита; возможность смещения зависит от потока. |
CachingStream($stream, $target = null) | Повторно читать уже полученные данные | Прочитанные данные сохраняются в target, по умолчанию php://temp. |
NoSeekStream($stream) | Убрать возможность seek у обёрнутого потока | Попытка seek вызывает ошибку. |
DroppingStream($stream, $maxLength) | Обрезать последующие записи по максимальному размеру | Лишние байты не сохраняются; проверяйте фактически записанную длину. |
InflateStream($stream) | Читать распакованный gzip/deflate-поток | Нужны подходящие PHP stream filters и корректный compressed input. |
MultipartStream($elements = [], $boundary = null) | Сформировать multipart body | contents элемента передаётся через текущий stream_for() с его ограниченной сигнатурой. |
FnStream($methods) | Переопределить операции callable-методами | Не предназначен для unserialize; пробрасывает ошибки предоставленных callback. |
StreamDecoratorTrait делегирует общие stream-методы обёрнутому объекту; StreamWrapper даёт доступ через PHP stream wrapper. Эти адаптеры не добавляют ownership isolation: закрытие общего underlying stream влияет на остальные обёртки.
Чтение и закрытие
Заголовок раздела «Чтение и закрытие»read($length) возвращает не более указанного количества байт; getContents() читает оставшиеся. Перед чтением всего тела проверяйте размер и лимиты приложения. getSize() может вернуть null; это не нулевой размер.
seek() и rewind() требуют seekable-потока. Stream выбрасывает RuntimeException для detached resource, неподдерживаемой операции или ошибки чтения/записи. read() с отрицательной длиной вызывает RuntimeException; нулевая длина возвращает пустую строку.
BufferStream::write() сначала добавляет данные, а при достижении high-water mark возвращает false, приводимое объявленным int return type к 0. Нельзя интерпретировать это как «данные не попали в буфер» или жёсткое ограничение памяти.
Строки HTTP и helpers
Заголовок раздела «Строки HTTP и helpers»Функции импортируются явно:
use function localzet\PSR7\stream_for;use function localzet\PSR7\parse_query;| Функции | Назначение |
|---|---|
stream_for(string $value = '', array $options = []) | Создать поток из строки. Старые комментарии о resource/callback шире реальной сигнатуры. |
str($message), response_to_string($response) | Сформировать текстовое HTTP-представление сообщения/ответа. |
parse_request($message), parse_response($message) | Разобрать HTTP-строку в Request/Response; некорректный формат вызывает InvalidArgumentException. |
uri_for($uri) | Получить URI из строки либо существующего UriInterface. |
parse_header($header), normalize_header($header) | Разобрать значения заголовков и параметры. |
parse_query($query, $urlEncoding = true), build_query($params, $encoding = PHP_QUERY_RFC3986) | Преобразовать query string и карту параметров. |
rewind_body($message) | Перемотать body к началу, когда требуется. |
copy_to_string($stream, $maxLen = -1), copy_to_stream($source, $destination, $maxLen = -1) | Скопировать данные из потока. -1 не ограничивает объём. |
hash($stream, $algorithm, $rawOutput = false) | Вычислить хеш содержимого потока. |
readline($stream, $maxLength = null) | Прочитать строку из потока. |
try_fopen($filename, $mode) | Открыть resource с преобразованием ошибки в исключение. |
mimetype_from_filename(), mimetype_from_extension() | Получить предполагаемый media type по расширению; это не проверка реального содержимого файла. |
get_message_body_summary($message, $truncateAt = 120) | Получить краткое представление body для диагностики. Не отправляйте туда секретное тело запроса. |
Служебные функции с _ в начале и Rfc7230 используются парсером; на них не стоит строить отдельный внешний контракт приложения.
URI helpers
Заголовок раздела «URI helpers»UriResolver::resolve($base, $relative) разрешает относительный URI; removeDotSegments() обрабатывает сегменты ./..; relativize() строит относительную форму. UriNormalizer предоставляет нормализацию и сравнение с заданными флагами.
Нормализация не равна проверке безопасности. Не сравнивайте доступ к внешним ресурсам только по красивому строковому представлению: учитывайте итоговый host, scheme, port и политику transport.
Загруженные файлы
Заголовок раздела «Загруженные файлы»UploadedFile::getStream() недоступен после ошибки загрузки или успешного moveTo(). moveTo() требует непустой путь; повторное перемещение после успеха вызывает RuntimeException. Для файла на диске CLI использует rename(), веб-режим — move_uploaded_file(); для stream-backed upload данные копируются в целевой поток.
Методы getClientFilename() и getClientMediaType() возвращают заявленную клиентом информацию. Выбирайте имя назначения сами, проверяйте лимит размера и допустимое содержимое. ServerRequest::normalizeFiles() преобразует структуру $_FILES в UploadedFile-объекты; отдельно проверьте, какую структуру вернул используемый parser Server.