Документация/Контейнер/Сервисы/Request

Объект Request

Системный объект Request создается в самом начале обработки HTTP-запроса фреймворком. Он не только создается, но и заполняется информацией (заголовками, параметрами и т.д.)
С его помощью производится начальное функционирование фреймворка HLEB2, обрабатывающего запрос. Системный Request предназначен только для этого.

Сервис Request, который по умолчанию может быть получен из контейнера и с помощью которого можно использовать данные текущего запроса, является оберткой над системным объектом.

Способы получения данных из Request в контроллерах (и всех классах, унаследованных от Hleb\Base\Container) на примере текущего HTTP-метода:

// variant 1
use Hleb\Reference\RequestInterface;
$method = $this->container->get(RequestInterface::class)->getMethod();

// variant 2
$method = $this->container->request()->getMethod();

// variant 3
$method = $this->request()->getMethod();

Пример получения HTTP-метода из Request в коде приложения:

// variant 1
use Hleb\Static\Container;
use Hleb\Reference\RequestInterface;
$method = Container::get(RequestInterface::class)->getMethod();

// variant 2
use Hleb\Static\Request;
$method = Request::getMethod();

Также объект Request может быть получен через внедрение зависимостей по интерфейсу Hleb\Reference\Interface\Request.

Для упрощения примеров, далее они будут содержать только обращение через Hleb\Static\Request.

#HTTP-метод запроса

Запрос к приложению выполняется с определённым HTTP-методом, во фреймворке поддерживаются следующие: 'GET', 'POST', 'DELETE', 'PUT', 'PATCH', 'OPTIONS' (и 'HEAD').
Определить текущий помогают методы getMethod() и isMethod(). Первый возвращает значение, например 'GET', а в методе isMethod(...) нужно указать искомое значение для сравнения.

#Параметры из $_GET, $_POST и тела запроса

Данные, переданные вместе с запросом, могут в дальнейшем использоваться по-разному. Они могут быть сохранены в исходном виде, тогда предварительная обработка не требуется. Но если необходимо отобразить их сразу в ответе, то нужно обезопасить данные от внедрения исполняемых скриптов. Методы get() и post() возвращают объект с соответствующим параметром, при помощи этого объекта можно получить как необработанные данные, так и преобразованные в нужном формате.

use Hleb\Static\Request;

// (!) Original raw data.
$rawValue = Request::get('param')->value();

// Validated data converted to string.
$clearedStringValue = Request::get('param')->asString();

// Data converted to an integer.
$integerValue = Request::get('param')->asInt();

// Data checked for a positive integer.
$positiveIntegerValue = Request::get('param')->asPositiveInt();

Наиболее частой ошибкой при использовании объекта, возвращаемого этими методами, может быть использование этого объекта как значения, вместо получения значения из объекта.

При необходимости получить результат как массив, например для запроса с '?param[key]=value', объект со значением имеет метод asArray(), в котором значения массива будут обработаны от XSS-уязвимостей, также метод value() вернёт массив, но в нём будут исходные необработанные данные.

Метод input() служит для определения и получения массива данных из тела запроса. Это могут быть JSON-данные или кодированные url-encoded параметры, преобразованные в массив.
Таким образом, можно получить в виде массива POST-, PUT-, PATCH- или DELETE-параметры или переданные параметры в теле запроса в формате JSON.

Данные, полученные методом input(), представляют собой обработанные значения с преобразованными в спецсимволы HTML-тегами.

Если необходимо получить данные тела запроса в исходном виде как массив, то для этого предназначен метод getParsedBody(). Он аналогичен input(), только возвращает данные в необработанном виде.

Если предыдущие форматы не подошли, то тело запроса в исходном виде, как строковое значение, возвращает метод getRawBody(). Таким образом, можно преобразовать данные в нужный формат самостоятельно.

#Параметры динамического маршрута

К таким параметрам запроса относятся динамические части маршрута, в запросе им соответствуют определенные значения. Получить эти значения по названию динамического параметра позволяет метод param(). Результатом будет объект, через методы которого можно получить значение в нужном формате.

Например, если c запросом совпал маршрут такого вида:

Route::get('/{version}/{page}/')->controller(ExampleController::class);

Для адреса /10/main/ параметры 'version' и 'page' определяются следующим образом:

use Hleb\Static\Request;

$page = Request::param('page')->asString(); // main

$version = Request::param('version')->asPositiveInt(); // 10

Наиболее частой ошибкой при использовании объекта, возвращаемого этим методом, может быть использование этого объекта как значения, вместо получения значения из объекта.

Метод data() возвращает массив объектов для всех динамических параметров. Из этих объектов аналогично могут быть получены значения параметров в исходном и обработанном виде.

Получить исходные динамические параметры маршрута как массив значений без обработки позволяет метод rawData().

Необходимо учесть, что фреймворк при обработке входящих данных (когда это выбрано) защищает только от XSS-атак, в других случаях, например, когда требуется экранирование кавычек при сохранении в базу данных, нужно применить дополнительные меры защиты.

#Данные URI запроса

Основой для объекта, возвращаемого методом getUri(), взят UriInterface из PSR-7, благодаря этому можно получить следующие данные запроса:
getUri()->getHost() - доменное имя текущего запроса, например - 'mob.example.com'. Может быть вместе с портом, в зависимости от наличия его в запросе.
getUri()->getPath() - путь из адреса после хоста, например '/ru/example/page' или '/ru/example/page/'.
getUri()->getQuery() - параметры запроса, например '?param1=value1&param2=value2'.
getUri()->getPort() - порт запроса.
getUri()->getScheme() - HTTP-схема запроса, 'http' или 'https'.
getUri()->getIp() - IP-адрес запроса.

#HTTP-схема запроса

Для уточнения типа HTTP-схемы запроса можно воспользоваться методом isHttpSecure(). Он вернет результат проверки схемы на 'https'.

Метод getHttpScheme() возвращает текущую HTTP-схему запроса как 'http://' или 'https://'.

#Получение хоста из адреса

Метод getHost() предназначен для получения доменного имени текущего запроса. Аналогичен getUri()->getHost().

Вместе с HTTP-схемой получить хост адреса можно при использовании метода getSchemeAndHost().

#URL запроса

Метод getAddress() возвращает полный URL запроса без GET-параметров.

#Загрузка файлов

При загрузке файла или файлов пользователем, получить их данные позволяет метод getFiles(). Возвращает массив массивов с данными или массив объектов, в зависимости от того, был ли фреймворк инициирован c внешним Request.

#Заголовки запроса

Массив всех заголовков входящего запроса возвращает метод getHeaders(). Это заголовки запроса, отсортированные по ключу(названию).

Проверить наличие заголовка по названию можно через метод hasHeader().

Метод getHeader() по названию возвращает массив соответствующих заголовков (значений).

Метод getHeaderLine() также возвращает значения заголовка по названию, но в виде строки как перечисление.

#Данные $_SERVER

Для получения данных, которые установлены веб-сервером в переменной $_SERVER, можно воспользоваться методом server(). Он возвращает значение по имени параметра.

#Версия протокола запроса

Метод getProtocolVersion() возвращает версию протокола запроса, например '1.1'.

← Внедрение зависимостей Response →

Страница создана: @fomiash

Репозиторий проекта: github.com/phphleb. Группа поддержки в Телеграм - @phphleb

Обучающие видео-материалы на YouTube и Rutube.

Задать вопрос в блоге, который сделан с использованием фреймворка HLEB.

Этот сайт-инструкция к фреймворку HLEB2 сделан с использованием фреймворка HLEB2.

Если вы обнаружили ошибку на странице, сообщите автору или предложите правку.

PHP Framework HLEB2

HLEB2