03 - PSR-7 HTTP Запрос

Обзор

Phalcon\Http\Message\Request -Запрос является реализацией интерфейса обмена сообщениями PSR-7 HTTP как это определено PHP-FIG.

Эта реализация была создана для установления стандарта между реализациями промежуточного программного обеспечения. Приложениям часто нужно отправлять запросы на внешние конечные точки. Для этого вы можете использовать объект Phalcon\Http\Message\Request. В ответ наше приложение получит ответный объект.

ПРИМЕЧАНИЕ Phalcon не ограничивает вас в использовании определенного HTTP-клиента. Любой клиент, совместимый с PSR-7, будет работать с этим компонентом, чтобы вы могли выполнять ваши запросы.

ПРИМЕЧАНИЕ: В приведенных ниже примерах $httpClient - это клиент по вашему выбору, который реализует PSR-7.

<?php

use Phalcon\Http\Message\Request;
use Phalcon\Http\Message\Uri;

$request = new Request();
$uri     = new Uri('https://api.phalcon.io/companies/1');

$jwtToken = 'abc.def.ghi';

$request = $request
   ->withMethod('POST')
   ->withHeader('Authorization', 'Bearer ' . $jwtToken)
   ->withHeader('Content-Type', 'application/json')
;

$result = $httpClient->send($request);

Мы создаем новый объект Phalcon\Http\Message\Request и новый объект Phalcon\Http\Message\Uri с целевым URL. После этого мы определяем метод (POST) и дополнительные заголовки, которые нам нужно отправить с нашим запросом. Затем клиент отправляет запрос, используя объект запроса.

Приведенный выше пример может быть реализован только с использованием параметров конструктора:

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => 'application/json',
    ]
);

$result = $httpClient->send($request);

Созданный объект Phalcon\Http\Message\Request является неизменным, то есть он никогда не изменится. Любой вызов методов с префиксом with* вернет клон объекта для сохранения неизменности в соответствии со стандартом.

Конструктор

public function __construct(
    [string $method = "GET" 
    [, mixed $uri = null 
    [, mixed $body = "php://temp" 
    [, array $headers = [] ]]]]
)

Конструктор принимает параметры, позволяющие создать объект с определенными заполненными свойствами. Вы можете определить целевой метод HTTP, URL, тело, а также заголовки. Все параметры являются необязательными.

method - по умолчанию GET. Поддерживаемые методы: GET, CONNECT, DELETE, HEAD, OPTIONS, PATCH, POST, PUT, TRACE
uri - экземпляр Phalcon\Http\Message\Uri или URL.
body - по умолчанию php://memory. Метод принимает либо объект, который реализует интерфейс StreamInterface, либо строку, такую как имя потока. Режим по умолчанию для потока - w+b. Если пропущен недопустимый поток, генерируется исключение InvalidArgumentException
headers - Массив значений ключа, с ключом в качестве имени заголовка и значением в качестве значения заголовка.

Геттеры

`getBody()`

Возвращает тело как объект StreamInterface

<?php

use Phalcon\Http\Message\Request;
use Phalcon\Http\Message\Stream;

$jwtToken = 'abc.def.ghi';
$fileName = dataFolder('/assets/stream/mit.txt');
$stream   = new Stream($fileName, 'rb');

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    $stream,
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => 'application/json',
    ]
);

echo $request->getBody(); // '/assets/stream/mit.txt'

`getHeader()`

Возвращает массив всех значений заголовка переданного без учета регистра имени заголовка. Если строковый параметр, представляющий запрашиваемое имя заголовка, отсутствует, возвращается пустой массив.

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => 'application/json',
    ]
);

echo $request->getHeader('content-Type'); // ['application/json']
echo $request->getHeader('unknown');      // []

`getHeaderLine()`

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

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => [
            'application/json',
            'application/html',
        ],
    ]
);

echo $request->getHeaderLine('content-Type'); // 'application/json,application/html'

`getHeaders()`

Возвращает массив со всеми значениями заголовка сообщения. Ключи представляют имя заголовка, так как оно будет отправлено по проводам, а каждое значение представляет собой массив строк, связанных с заголовком. Хотя имена заголовков не чувствительны к регистру, этот метод сохраняет точный регистр, в котором заголовки были изначально указаны.

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => [
            'application/json',
            'application/html',
        ],
    ]
);

var_dump(
    $request->getHeaders()
);
// [
//     'Authorization' => 'Bearer abc.def.ghi',
//     'Content-Type'  => [
//         'application/json',
//         'application/html',
//     ],
// ]

`getMethod()`

Возвращает метод в виде строки

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => 'application/json',
    ]
);

echo $request->getMethod(); // POST

`getProtocolVersion()`

Возвращает версию протокола в виде строки (по умолчанию 1.1)

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => 'application/json',
    ]
);

echo $request->getProtocolVersion(); // '1.1'

`getRequestTarget()`

Возвращает строку, представляющую цель запроса сообщения, либо в том виде, в каком оно будет отображаться (для клиентов), в том виде, в котором оно появилось в запросе (для серверов), или в том виде, в котором оно было указано для экземпляра (см. withRequestTarget()). В большинстве случаев это будет исходная форма составленного URI, если только значение не было предоставлено конкретной реализации (см. withRequestTarget()).

<?php

use Phalcon\Http\Message\Request;

$request = new Request();
$request = $request->withRequestTarget('/test');

echo $request->getRequestTarget(); // '/test'

`getUri()`

Возвращает Uri как объект UriInterface

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => 'application/json',
    ]
);

echo $request->getUri(); // UriInterface : https://api.phalcon.io/companies/1

Существование

`hasHeader()`

Проверяет, существует ли заголовок с заданным нечувствительным к регистру именем. Возвращает true , если заголовок был найден, false в противном случае

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => [
            'application/json',
            'application/html',
        ],
    ]
);

echo $request->hasHeader('content-type'); // true

С

Объект запроса является неизменяемым. Однако существует ряд методов, позволяющих вводить в него данные. Возвращаемый объект является клоном исходного объекта.

`withAddedHeader()`

Возвращает экземпляр с дополнительным заголовком, добавленным к заданному значению. Существующие значения для указанного заголовка будут сохранены. Новое значение(ы) будет добавлено к существующему списку. Если заголовок ранее не существовал, он будет добавлен. Создает исключение InvalidArgumentException для недопустимых имен заголовков или значений. Значения заголовка могут быть строкой или массивом строк.

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => [
            'application/json',
        ],
    ]
);

var_dump(
    $request->getHeaders()
);
// [
//     'Authorization' => 'Bearer abc.def.ghi',
//     'Content-Type'  => [
//         'application/json',
//     ],
// ]

$clone = $request
    ->withAddedHeader(
        'Content-Type', 
        [
            'application/html'
        ]
    );

var_dump(
    $clone->getHeaders()
);
// [
//     'Authorization' => 'Bearer abc.def.ghi',
//     'Content-Type'  => [
//         'application/json',
//         'application/html',
//     ],
// ]

`withBody()`

Возвращает экземпляр с указанным телом сообщения, который реализует StreamInterface. Создает исключение InvalidArgumentException, когда тело недопустимо.

<?php

use Phalcon\Http\Message\Request;
use Phalcon\Http\Message\Stream;

$jwtToken = 'abc.def.ghi';
$fileName = dataFolder('/assets/stream/mit.txt');
$stream   = new Stream($fileName, 'rb');

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => 'application/json',
    ]
);

$clone = $request->withBody($stream);

echo $clone->getBody(); // '/assets/stream/mit.txt'

`withHeader()`

Возвращает экземпляр с предоставленным значением, заменяющим указанный заголовок. В то время как имена заголовков не чувствительны к регистру, оболочка заголовка будет сохранена этой функцией и возвращена из getHeaders(). Создает исключение InvalidArgumentException для недопустимых имен заголовков или значений.

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
    ]
);

var_dump(
    $request->getHeaders()
);
// [
//     'Authorization' => 'Bearer abc.def.ghi',
// ]

$clone = $request->withAddedHeader(
    'Content-Type',
    [
        'application/html',
    ]
);

var_dump(
    $clone->getHeaders()
);
// [
//     'Authorization' => 'Bearer abc.def.ghi',
//     'Content-Type'  => [
//         'application/html',
//     ],
// ]

`withMethod()`

Возвращает экземпляр с предоставленным методом HTTP в виде строки. Создает исключение InvalidArgumentException для недопустимых методов HTTP.

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => 'application/json',
    ]
);

echo $request->getMethod(); // POST

$clone = $request->withMethod('GET');

echo $clone->getMethod(); // GET

`withProtocolVersion()`

Возвращает экземпляр с указанной версией протокола HTTP (в виде строки).

<?php

use Phalcon\Http\Message\Request;

$request  = new Request();

echo $request->getProtocolVersion(); // '1.1'

$clone = $request->withProtocolVersion('2.0');

echo $clone->getProtocolVersion(); // '2.0'

`withRequestTarget()`

Возвращает экземпляр с определенным целевым запросом.

<?php

use Phalcon\Http\Message\Request;

$request = new Request();

echo $request->getRequestTarget(); // "/"

$clone = $request->withRequestTarget('/test');

echo $clone->getRequestTarget(); // '/test'

`withUri()`

Возвращает экземпляр с предоставленным URI UriInterface. Этот метод обновляет заголовок Host возвращенного запроса по умолчанию, если URI содержит компонент host. Если URI не содержит компонент хоста, любой ранее существующий заголовок хоста будет перенесен в возвращенный запрос.

Вы можете отказаться от сохранения исходного состояния заголовка Host, установив для $preserveHost значение true. Когда $preserveHost имеет значение true, этот метод взаимодействует с заголовком Host следующими способами:

Если заголовок узла отсутствует или пуст, а новый URI содержит компонент узла, этот метод обновит заголовок узла в возвращенном запросе.
Если заголовок Host отсутствует или пуст, а новый URI не содержит компонент Host, этот метод не будет обновлять заголовок Host в возвращенном запросе.
Если заголовок Host присутствует и не пуст, этот метод не будет обновлять заголовок Host в возвращенном запросе.

<?php

use Phalcon\Http\Message\Request;

$query   = 'https://phalcon.io';
$uri     = new Uri($query);
$request = new Request();

$clone = $request->withUri($uri);

echo $clone->getRequestTarget(); // 'https://phalcon.io'

`withoutHeader()`

Вернуть экземпляр без указанного заголовка.

<?php

use Phalcon\Http\Message\Request;

$jwtToken = 'abc.def.ghi';

$request = new Request(
    'POST',
    'https://api.phalcon.io/companies/1',
    'php://memory',
    [
        'Authorization' => 'Bearer ' . $jwtToken,
        'Content-Type'  => [
            'application/json',
        ],
    ]
);

var_dump(
    $request->getHeaders()
);
// [
//     'Authorization' => 'Bearer abc.def.ghi',
//     'Content-Type'  => [
//         'application/json',
//     ],
// ]

$clone = $request->withoutHeader('Content-Type');

var_dump(
    $clone->getHeaders()
);
// [
//     'Authorization' => 'Bearer abc.def.ghi',
// ]