02 - Быстрый старт

Оглавление

На этой странице приводится краткое введение Guzzle and introductory examples. Если вы еще не установили Guzzle, зайдите на страницу установки.

Выполнение запроса

Вы можете отправить запросы с Guzzle, используя объект GuzzleHttp\ClientInterface.

Создание клиента

use GuzzleHttp\Client;

$client = new Client([
    //Базовый URI используется с относительными запросами
    'base_uri' => 'http://httpbin.org',
    // Вы можете установить любое количество опций запроса по умолчанию.
    'timeout'  => 2.0,
]);

Клиенты неизменны в Guzzle 6, что означает, что Вы не можете изменить значения по умолчанию, используемые клиентом после того, как он создается.

Конструктор клиента принимает ассоциативный массив опций:

base_uri: Базовый URI (string|UriInterface) клиента, который объединяется с относительным URIs. Может быть строка или экземпляр класса UriInterface. Когда относительный URI будет предоставлен клиенту, клиент объединит основной URI с относительным URI, используя правила, описанные в RFC 3986, section 2.

// Создание клиента с базовым URI
$client = new GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']);
// Отправить запрос на https://foo.com/api/test
$response = $client->request('GET', 'test');
// Отправить запрос на https://foo.com/root
$response = $client->request('GET', '/root');

Не хочется читать RFC 3986? Вот некоторые быстрые примеры того, какbase_uri решается с другим URI.

base_uri	URI	Result
`http://foo.com`	`/bar`	`http://foo.com/bar`
`http://foo.com/foo`	`/bar`	`http://foo.com/bar`
`http://foo.com/foo`	`bar`	`http://foo.com/bar`
`http://foo.com/foo/`	`bar`	`http://foo.com/foo/bar`
`http://foo.com`	`http://baz.com`	`http://baz.com`
`http://foo.com/?bar`	`bar`	`http://foo.com/bar`

handler

(callable) Функция передает http-запросы по сети Функция вызывается с Psr7\Http\Message\RequestInterfaceи массивом опций передачи,и должна возвращать GuzzleHttp\Promise\PromiseInterface выполняющуюся с Psr7\Http\Message\ResponseInterface в случае успеха. handler - параметр только конструктора, он не может быть переопределен в опциях per/request.

...

(Смешанные) Все другие параметры, передаваемые конструктору используются в качестве параметров запроса по умолчанию при каждом запросе созданного клиентом.

Отправка запросов

Магические методы клиента позволяют легко посылать синхронные запросы:

$response = $client->get('http://httpbin.org/get');
$response = $client->delete('http://httpbin.org/delete');
$response = $client->head('http://httpbin.org/get');
$response = $client->options('http://httpbin.org/get');
$response = $client->patch('http://httpbin.org/patch');
$response = $client->post('http://httpbin.org/post');
$response = $client->put('http://httpbin.org/put');

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

use GuzzleHttp\Psr7\Request;

$request = new Request('PUT', 'http://httpbin.org/put');
$response = $client->send($request, ['timeout' => 2]);

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

Вы можете узнать больше о клиентском промежуточном программном обеспечении на странице Обработчики и промежуточное программное обеспечение документации.

Асинхронные запросы

Вы можете отправить асинхронные запросы, используя волшебные методы, предоставленные клиентом:

$promise = $client->getAsync('http://httpbin.org/get');
$promise = $client->deleteAsync('http://httpbin.org/delete');
$promise = $client->headAsync('http://httpbin.org/get');
$promise = $client->optionsAsync('http://httpbin.org/get');
$promise = $client->patchAsync('http://httpbin.org/patch');
$promise = $client->postAsync('http://httpbin.org/post');
$promise = $client->putAsync('http://httpbin.org/put');

Вы можете также использовать sendAsync () и requestAsync () методы клиента:

use GuzzleHttp\Psr7\Request;

// Создать объект запроса PSR-7 для  отправки
$headers = ['X-Foo' => 'Bar'];
$body = 'Hello!';
$request = new Request('HEAD', 'http://httpbin.org/head', $headers, $body);

// Или, если Вы не должны передавать в экземпляре запроса:
$promise = $client->requestAsync('GET', 'http://httpbin.org/get');

Ообработчик прерывания, возвращенний этими методами, реализует спецификацию Promises/A+ spec, обеспечиваемую Guzzle promises library. Это означает, что Вы можете объединить в цепочку then() вызовы обработчиков. Затем эти вызовы либо выполнены с успешной Psr\Http\Message\ResponseInterfaceили отвергаются с исключением.

use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\Exception\RequestException;

$promise = $client->requestAsync('GET', 'http://httpbin.org/get');
$promise->then(
    function (ResponseInterface $res) {
        echo $res->getStatusCode() . "\n";
    },
    function (RequestException $e) {
        echo $e->getMessage() . "\n";
        echo $e->getRequest()->getMethod();
    }
);

Параллельные запросы

Вы можете отправить несколько запросов одновременно, используя прерывания к асинхронным запросам.

use GuzzleHttp\Client;
use GuzzleHttp\Promise;

$client = new Client(['base_uri' => 'http://httpbin.org/']);

// Инициировать каждый запрос, но не блокировать
$promises = [
    'image' => $client->getAsync('/image'),
    'png'   => $client->getAsync('/image/png'),
    'jpeg'  => $client->getAsync('/image/jpeg'),
    'webp'  => $client->getAsync('/image/webp')
];

// Ожидать завершения прерывания по всем запросам.
// инициировать исключение ConnectException при любом сбое
$results = Promise\unwrap($promises);

// Ожидать завершения запросов,  даже если некоторые из них перестали работать
$results = Promise\settle($promises)->wait();

// Вы можете получить доступ к каждому результату, используя ключ, предоставленный   
// функцией unwrap.
echo $results['image']->getHeader('Content-Length');
echo $results['png']->getHeader('Content-Length');

Вы можете использовать объект GuzzleHttp\Pool , когда вы хотите отправить неопределенное количество запросов.

use GuzzleHttp\Pool;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

$client = new Client();

$requests = function ($total) {
    $uri = 'http://127.0.0.1:8126/guzzle-server/perf';
    for ($i = 0; $i < $total; $i++) {
        yield new Request('GET', $uri);
    }
};

$pool = new Pool($client, $requests(100), [
    'concurrency' => 5,
    'fulfilled' => function ($response, $index) {
        // this is delivered each successful response
    },
    'rejected' => function ($reason, $index) {
        // this is delivered each failed request
    },
]);

// Инициировать передачи и создать обещание.
$promise = $pool->promise();

// Инициировать выполнение пула запросов 
$promise->wait();

Или используя закрытие, которое возвратит прерывание, как только пул вызывает закрытие..

$client = new Client();

$requests = function ($total) use ($client) {
    $uri = 'http://127.0.0.1:8126/guzzle-server/perf';
    for ($i = 0; $i < $total; $i++) {
        yield function() use ($client, $uri) {
            return $client->getAsync($uri);
        };
    }
};

$pool = new Pool($client, $requests(100));

Использование ответов

В предыдущих примерах, мы получаем переменную $response или был доставлен ответ от прерывания.Объект ответа реализует PSR-7 ответ Psr\Http\Message\ResponseInterface, и содержит много полезной информации.

Вы можете получить код состояния и сообщение ответа:

$code = $response->getStatusCode(); // 200
$reason = $response->getReasonPhrase(); // OK

Вы можете получить заголовки из ответа:

// проверить, если заголовок существует.
if ($response->hasHeader('Content-Length')) {
    echo "It exists";
}

// Получить заголовок из ответа.
echo $response->getHeader('Content-Length');

// Получить все заголовки ответа.
foreach ($response->getHeaders() as $name => $values) {
    echo $name . ': ' . implode(', ', $values) . "\r\n";
}

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

$body = $response->getBody();
// Неявное приведение тела в строку, и вывести его
echo $body;
// Явно привести тело в строку
$stringBody = (string) $body;
// Прочитать 10 байтов тела
$tenBytes = $body->read(10);
// Прочитайте оставшееся содержимое тела в виде строки
$remainingBytes = $body->getContents();

Параметры Строки Запроса

Вы можете предоставить параметры строки запроса несколькими способами.

Вы можете задать параметры строки запроса в запрос по URI:

$response = $client->request('GET', 'http://httpbin.org?foo=bar');

Можно задать параметры строки запроса, используя параметр queryв виде массива.

$client->request('GET', 'http://httpbin.org', [
    'query' => ['foo' => 'bar']
]);

Возможность в качестве массива использовать PHP функции http_build_queryв формате строки запроса.

И, наконец, можно предусмотреть вариант queryзапроса в виде строки.

$client->request('GET', 'http://httpbin.org', ['query' => 'foo=bar']);

Загрузка данных

Guzzle предоставляет несколько методов для загрузки данных.

Вы можете посылать запросы, которые содержат поток данных, передавая строку, ресурс возвращаемый из fopen, или экземпляр Psr\Http\Message\StreamInterface в параметре body запроса.

// Обеспечить тело в виде строки.
$r = $client->request('POST', 'http://httpbin.org/post', [
    'body' => 'raw data'
]);

// Обеспечить FOPEN ресурс.
$body = fopen('/path/to/file', 'r');
$r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]);

// Использовать функцию stream_for() для создания потока PSR-7.
$body = \GuzzleHttp\Psr7\stream_for('hello!');
$r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]);

Самый простой способ для загрузки данных в формате JSON и установить соответствующий заголовок использует параметр запроса json:

$r = $client->request('PUT', 'http://httpbin.org/put', [
    'json' => ['foo' => 'bar']
]);

Запросы POST/Формы

Помимо определения исходных данных запроса с помощью опции запроса body, Guzzle дает полезные абстракции для отправки данных POST.

Отправка полей формы

При отправке application/x-www-form-urlencoded запроса POST нужно указать поля POST как массив в параметре запроса form_params.

$response = $client->request('POST', 'http://httpbin.org/post', [
    'form_params' => [
        'field_name' => 'abc',
        'other_field' => '123',
        'nested_field' => [
            'nested' => 'hello'
        ]
    ]
]);

Отправка формы с файлами

Вы можете отправлять файлы вместе с формой(multipart/form-dataзапросы POST),с помощью параметра multipart. multipartпринимает массив ассоциативных массивов, где каждый ассоциативный массив содержит следующие разделы:

name: (обязательное, string) ключ - имя поля формы.
contents: (required, mixed) Обеспечить строку, чтобы отправить содержимое файла в виде строки, обеспечивают FOPEN ресурс для потоковой передачи содержимого из PHP потока, или предоставить Psr\Http\Message\StreamInterfaceдля потоковой передачи содержимого из PSR-7 потока.

$response = $client->request('POST', 'http://httpbin.org/post', [
    'multipart' => [
        [
            'name'     => 'field_name',
            'contents' => 'abc'
        ],
        [
            'name'     => 'file_name',
            'contents' => fopen('/path/to/file', 'r')
        ],
        [
            'name'     => 'other_file',
            'contents' => 'hello',
            'filename' => 'filename.txt',
            'headers'  => [
                'X-Foo' => 'это дополнительный заголовок, для включения'
            ]
        ]
    ]
]);

Куки

Guzzle может поддерживать куки сессии для вас, если указать с помощью параметра запроса cookies.При отправке запроса, в параметр cookies должен быть установлен экземпляр интерфейса GuzzleHttp\Cookie\CookieJarInterface.

// Используйте конкретный клиент куков
$jar = new \GuzzleHttp\Cookie\CookieJar;
$r = $client->request('GET', 'http://httpbin.org/cookies', [
    'cookies' => $jar
]);

Вы можете установить cookies как trueв конструктор клиента, если вы хотели бы использовать общих куков для всех запросов.

// Используйте общий клиент куков
$client = new \GuzzleHttp\Client(['cookies' => true]);
$r = $client->request('GET', 'http://httpbin.org/cookies');

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

Guzzle будет автоматически следовать редиректам, если вы не скажете ему не делать этого. Вы можете настроить поведение переадресации с помощью опции allow_redirects.

Установите trueдля того, чтобы нормальные переадресовывает с максимальным числом 5 переадресаций. Это значение по умолчанию.
Установите falseчтобы отключить редиректы.
Поставьте ассоциативный массив, содержащий ключ 'max' с, чтобы указать максимальное количество переадресаций и при необходимости поставить ключ 'strict' , чтобы указать, следует ли использовать строгие RFC-совместимые перенаправления (что означает перенаправление запросов POST с запросами POST против того, что делает большенство браузеров которые перенаправляют запросы POST как GET).

$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200

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

$response = $client->request('GET', 'http://github.com', [
    'allow_redirects' => false
]);
echo $response->getStatusCode();
// 301

Исключения

Guzzle выдает исключения для ошибок, которые возникают во время передачи.

В случае ошибки сети (соединения тайм-аута, ошибки DNS, и т.д.), выбрасывается GuzzleHttp\Exception\RequestException. Это исключение распространяется от GuzzleHttp\Exception\TransferException. Ловля это исключение будет ловить любое исключение, которое может быть выброшено при передаче запросов.
```
use GuzzleHttp\Psr7;
use GuzzleHttp\Exception\RequestException;

try {
    $client->request('GET', 'https://github.com/_abc_123_404');
} catch (RequestException $e) {
    echo Psr7\str($e->getRequest());
    if ($e->hasResponse()) {
        echo Psr7\str($e->getResponse());
    }
}
```
GuzzleHttp\Exception\ConnectException - исключение в случае ошибки сети. Это исключение распространяется от GuzzleHttp\Exception\RequestException.
A GuzzleHttp\Exception\ClientException выбрасывается на ошибки из группы 400, если параметр http_errors установлен как true. Это исключение наследуется от GuzzleHttp\Exception\BadResponseException и GuzzleHttp\Exception\BadResponseException распространяется от GuzzleHttp\Exception\RequestException.
```
use GuzzleHttp\Exception\ClientException;

try {
    $client->request('GET', 'https://github.com/_abc_123_404');
} catch (ClientException $e) {
    echo Psr7\str($e->getRequest());
    echo Psr7\str($e->getResponse());
}
```
GuzzleHttp\Exception\ServerExceptionвыбрасывается на ошибки из группы 500, если параметр http_errors установлен как true. Это исключение распространяется от GuzzleHttp\Exception\BadResponseException.
GuzzleHttp\Exception\TooManyRedirectsExceptionвыбрасывается, когда происходит слишком много переадресаций . Это исключение распространяется от GuzzleHttp\Exception\RequestException.

Все из вышеуказанных исключений распространяется от GuzzleHttp\Exception\TransferException.

Переменные окружения

Guzzle выставляет несколько переменных окружения, которые могут быть использованы для настройки поведения библиотеки.

GUZZLE_CURL_SELECT_TIMEOUT: Управляет продолжительностью в секундах, которые curl_multi_* обработчики будет использовать при выборе на вызовах curl, используя curl_multi_select(). У некоторых систем есть проблемы с реализацией PHP curl_multi_select(), где вызывание этой функции всегда приводит к ожиданию максимальной продолжительности тайм-аута.
HTTP_PROXY: Определяет прокси-сервер для использования при отправке запросов с использованием протокола "HTTP".
HTTPS_PROXY: Определяет прокси-сервер для использования при отправке запросов с помощью "HTTPS" протокола.

Соответствующие INI Настройки

Guzzle может использовать настройки PHP.ini при настройке клиентов.

openssl.cafile: Определяет путь на диске к файлу CA в формате PEM для использования при отправке запросов под "HTTPS". См: https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults

use GuzzleHttp\Psr7;
use GuzzleHttp\Exception\RequestException;

try {
    $client->request('GET', 'https://github.com/_abc_123_404');
} catch (RequestException $e) {
    echo Psr7\str($e->getRequest());
    if ($e->hasResponse()) {
        echo Psr7\str($e->getResponse());
    }
}

Оглавление