README

В PHP HTTP-запрос (request) представлен глобальными переменными ($_GET, $_POST, $_FILES, $_COOKIE, $_SESSION, ...), а ответ (response) генерируется функциями (echo, header(), setcookie(), ...)

Данный пакет заменяет эти стандартные глобальные переменные и функции PHP объектно-ориентированным слоем, инкапсулируя HTTP-запрос (request) и ответ (response) в объекты Fi1a\Http\RequestInterface и Fi1a\Http\ResponseInterface, которые предлагают удобный API для работы с ними.

Установка

Установить этот пакет можно как зависимость, используя Composer.

composer require fi1a/http

Хелперы

В пакете доступны следующие хелперы:

http(): HttpInterface - хелпер для HttpInterface;
request(?RequestInterface $request = null): RequestInterface - хелпер для текушего запроса;
response(?ResponseInterface $response = null): ResponseInterface - хелпер для текушего ответа;
session(?SessionStorageInterface $session = null): SessionStorageInterface - хелпер для доступа к сессии;
buffer(?BufferOutputInterface $buffer = null): BufferOutputInterface - хелпер для буферизированного вывода;
redirect($location = null, ?int $status = null, $headers = []): RedirectResponse - возвращает ответ для реализации перенаправления;
json($data = null, ?int $status = null, $headers = []): JsonResponseInterface - возвращает JSON-ответ.

Dependency injection

Контейнер dependency injection из пакета fi1a/dependency-injection

Для интерфейсов, в контейнере dependency injection, доступны следующие определения:

Fi1a\Http\HttpInterface;
Fi1a\Http\RequestInterface;
Fi1a\Http\ResponseInterface;
Fi1a\Http\Session\SessionStorageInterface;
Fi1a\Http\BufferOutputInterface;
Fi1a\Http\RedirectResponseInterface;
Fi1a\Http\JsonResponseInterface.

di()->get(Fi1a\Http\RequestInterface::class)->all();

HTTP-запрос

HTTP-запрос — это объект реализующий интерфейс Fi1a\Http\RequestInterface. HTTP-запрос является не изменяемым, у него нет сеттеров. Для доступа к текущему запросу можно использовать хелпер request().

request()->query()->get('foo'); // bar

Доступные методы Fi1a\Http\RequestInterface:

Методы post(), query(), all(), only(array $keys), options() возвращают результат в виде объекта, реализующего Fi1a\Collection\DataType\PathAccessInterface из пакета fi1a/collection

JSON-запрос

Если был передан заголовок Content-Type: application/json при запросе клиентом, то промежуточное ПО автоматически декодирует тело запроса из JSON-формата. Для того чтобы, получить доступ к декодированному значению вызовите метод body():

request()->rawBody(); // {"foo":"bar"}
request()->body(); // ['foo' => 'bar']

uri()

Возвращает URL-адрес запроса

request()->uri(); // https://domain.ru/path/?foo=bar

query()

Возвращает GET параметры запроса:

request()->query()->get('foo'); // bar

post()

Возвращает POST параметры запроса:

request()->post()->get('foo'); // bar

all()

Возвращает GET, POST, FILES, BODY параметры запроса:

request()->all()->get('foo'); // bar

only()

Только переданные ключи из параметров GET и POST:

request()->only(['foo'])->get('foo'); // bar

files()

Возвращает коллекцию Fi1a\Http\UploadFileCollectionInterface загруженных файлов Fi1a\Http\UploadFileInterface:

$collection = request()->files();
$uploadFile = $collection->get('some:file1');
$uploadFile->getName(); // file.txt

cookies()

Возвращает коллекцию Fi1a\Http\HttpCookieCollectionInterface cookies Fi1a\Http\HttpCookieInterface:

$collection = request()->cookies();
$cookie = $collection->getByName('cookieName');
$cookie->getValue(); // cookieValue

method()

Возвращает HTTP метод, с помощью которого был сделан запрос.

request()->method(); // POST

headers()

Возвращает все HTTP заголовки:

$headers = request()->headers();
$header = $headers->getLastHeader('X-Header');
$header->getValue(); // HeaderValue

HTTP-ответ

HTTP-ответ представляет собой объект Fi1a\Http\ResponseInterface. Он содержит всю информацию, которая должна быть отправлена клиенту для текущего запроса. Конструктор принимает до трех аргументов: статус ответа, массив заголовков HTTP и объект запроса Fi1a\Http\RequestInterface. Для доступа к текущему ответу можно использовать хелпер response().

use \Fi1a\Http\ResponseInterface;

$response = response()->withStatus(ResponseInterface::HTTP_INTERNAL_SERVER_ERROR);
response($response);

Установить новый текущий ответ:

use Fi1a\Http\Response;
use Fi1a\Http\ResponseInterface;

$response = new Response(ResponseInterface::HTTP_NOT_FOUND);
response($response);

Доступные методы Fi1a\Http\ResponseInterface:

withStatus(int $status, ?string $reasonPhrase = null)

Устанавливает код ответа состояния. Рекомендуется использовать предопределенные константы Fi1a\Http\ResponseInterface::HTTP_OK, ... вместо реальных чисел.

use Fi1a\Http\ResponseInterface;

$response = response()->withStatus(ResponseInterface::HTTP_OK, 'OK');
response($response);

withHeader(string $name, string $value)

Добавляет заголовок с определенным именем и значением к ответу:

$response = response()->withHeader('X-Header', 'Value');
response($response);

withoutHeader(string $name)

Удалить заголовки с определенным именем:

$response = response()->withoutHeader('X-Header');
response($response);

cookies

Возвращает cookies. Для того чтобы установить новую cookie, нужно добавить ее в коллекцию как в примере:

use Fi1a\Http\HttpCookie;

$cookie = new HttpCookie();
$cookie->setDomain('domain.ru');
$cookie->setName('CookieName');
$cookie->setPath('/');
$cookie->setValue('Value');

$response = response();
$response->cookies()->add($cookie);

buffer()->sendHeaders($response);

Cookie будет установлена при вызове метода sendHeaders класса Fi1a\Http\OutputInterface.

В фреймворке Elpha, нет необходимости вызывать метод sendHeaders класса Fi1a\Http\BufferOutputInterface, фреймворк это сделает за вас.

Отправка ответа

Отправка ответа клиенту осуществляется вызовом метода send() класса, реализующего интерфейс Fi1a\Http\BufferOutputInterface:

buffer()->send(response());

В фреймворке Elpha, нет необходимости вызывать метод send класса Fi1a\Http\BufferOutputInterface, фреймворк это сделает за вас.

Перенаправление

Перенаправление реализуется ответом с интерфейсом Fi1a\Http\RedirectResponseInterface. Можно воспользоваться хелперами:

use Fi1a\Http\ResponseInterface;

response(redirect()->to('/redirect/path', ResponseInterface::HTTP_MOVED_PERMANENTLY))

С помощью хелпера redirect мы создает ответ с перенаправлением по адресу '/redirect/path' и статусом ResponseInterface::HTTP_MOVED_PERMANENTLY и устанавливаем его используя response.

JSON-ответ

JSON-ответ реализуется интерфейсом Fi1a\Http\JsonResponseInterface. Можно воспользоваться хелперами:

response(json()->data(['foo' => 'bar']));

С помощью хелпера json мы создает JSON-ответ и устанавливаем его используя response. После установки JSON-ответа, промежуточное ПО устанавливает необходимые заголовки и выводит результат.

Сессия

Если у вас есть сессия, вы можете получить к ней доступ через хелпер session(). Сессия имеет интерфейс Fi1a\Http\SessionStorageInterface. Перед тем как получать или устанавливать значения в сессию, ее нужно открыть с помощью метода open().

В фреймворке Elpha, нет необходимости открывать сессию, фреймворк это сделает за вас.

$session = session();
if (!$session->isOpen()) {
    $session->open();
}

$session->getValues()->set('foo:bar', 'baz');
$session->getValues()->get('foo:bar'); // baz

$session->close();

Flush

Сохраняет значение в сессии. После получения значения, стирает его.

use Fi1a\Http\Flush;

if (!session()->isOpen()) {
    session()->open();
}

$flush = new Flush();

$flush->set('foo', 'bar');

$flush->get('foo'); // bar
$flush->get('foo'); // null

Uri

Класс реализующий интрефейс Fi1a\Http\UriInterface упрощает работу с URI и с его отдельными компонентами:

https://user:password@domain.ru:8080/url/path/?foo=bar#fragment
|----| |---| |------| |-------| |---||-------| |-----| |------|
  |      |      |        |        |     |         |        |
scheme  user password   host     port  path     query   fragment

Генерация Uri:

use Fi1a\Http\Uri;

$uri = new Uri();

$uri = $uri->withScheme('https')
    ->withHost('domain.ru')
    ->withPath('/path/')
    ->withQueryParams([
        'foo' => 'bar',
    ]);

$uri->uri(); // "https://domain.ru/path/?foo=bar"

Вы также можете задать URL-адрес строкой, а затем использовать его компоненты:

use Fi1a\Http\Uri;

$uri = new Uri('https://domain.ru/path/?foo=bar');

$uri->host(); // "domain.ru"
$uri->path(); // "/path/"

Доступные методы Fi1a\Http\UriInterface:

fi1a / http

Maintainers

Details