Guzzle в PHP: сравнение с cURL и 12 практических примеров

Получить пользователя из API, отправить JSON, передать файл, дождаться нескольких ответов — типичные задачи PHP-приложения. Guzzle помогает описывать такие запросы понятными массивами настроек, повторно использовать клиент и отдельно обрабатывать проблемы сети, HTTP и данных.

Начнём с главного: Guzzle — PHP-библиотека HTTP-клиента, cURL — инструмент передачи данных и расширение PHP для работы с libcurl. Они могут работать вместе: Guzzle часто отправляет запросы через cURL. Удобство библиотеки проявляется прежде всего в сборке запросов и организации кода, а не в обещании «ускорить любой API».

Примеры рассчитаны на PHP 8.2+ и Guzzle 7. Команды выполняются в терминале из папки проекта. Для практики приложен учебный сервер на вашем компьютере: внешние API и регистрация не нужны. На самой странице PHP не запускается. Если Composer ещё не установлен, откройте руководство «Composer в PHP: от первой команды до рабочего проекта».

1. Установка через Composer

В существующем PHP-проекте выполните:

composer require "guzzlehttp/guzzle:7.*"
composer show guzzlehttp/guzzle

Composer установит библиотеку и её зависимости в vendor/. Подключение vendor/autoload.php позволит использовать классы без ручных require для каждого файла. Не скачивайте отдельный Client.php: ему нужны остальные части пакета.

Для примеров этой статьи проще взять готовый проект. Скачайте ZIP, распакуйте, перейдите в папку, где лежит composer.json, и установите зафиксированные зависимости:

composer install
composer check-platform-reqs
php --ri curl

В архиве есть composer.lock, но нет vendor/: интернет нужен для первой установки пакетов. Для сравнения с нативным cURL и воспроизведения всех транспортных проверок включите расширение ext-curl именно у PHP командной строки. Сам Guzzle поддерживает разные обработчики транспорта; отсутствие cURL не всегда означает невозможность выполнить HTTP-запрос.

Документация: Guzzle: установка.

Документация: Нужен ли Guzzle cURL.

2. Guzzle и обычный cURL: понятное сравнение

Здесь сравниваем Guzzle с PHP-функциями curl_init(), curl_setopt_array(), curl_exec(). Команда curl в консоли — отдельная программа, хотя она решает похожие задачи.

Один GET двумя способами. В обоих случаях отправляем параметры и два заголовка, ограничиваем ожидание, запрещаем перенаправления, проверяем статус, JSON и структуру пользователя. Ниже — центральные фрагменты; полные запускаемые файлы находятся в архиве. Сервер запустим в следующем разделе.

Чтобы повторить сравнение целиком: запустите локальный сервер, затем во втором терминале выполните composer compare. В обоих фрагментах parseUser() — наша общая функция проверки ответа, а $query — массив параметров. Их определения доступны ниже.

<?php
declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

function parseUser(string $body): array
{
    $user = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    if (!is_array($user) || !isset($user['id'], $user['name'])
        || !is_int($user['id']) || !is_string($user['name'])) {
        throw new UnexpectedValueException('Ожидаются id:int и name:string.');
    }
    return $user;
}

$query = ['lang' => 'ru', 'include' => 'profile'];

Нативный PHP cURL:

$url = 'http://127.0.0.1:8095/users/7?'
    . http_build_query($query, '', '&', PHP_QUERY_RFC3986);
$curl = curl_init($url);
if ($curl === false) {
    throw new RuntimeException('Не удалось создать cURL handle.');
}
try {
    curl_setopt_array($curl, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Accept: application/json', 'X-Request-ID: demo-001'],
        CURLOPT_CONNECTTIMEOUT_MS => 1000,
        CURLOPT_TIMEOUT_MS => 2000,
        CURLOPT_FOLLOWLOCATION => false,
        CURLOPT_FAILONERROR => false,
        CURLOPT_PROXY => '', // Только для учебного localhost.
    ]);
    $body = curl_exec($curl);
    if ($body === false) {
        throw new RuntimeException('cURL ' . curl_errno($curl) . ': ' . curl_error($curl));
    }
    $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
    if ($status < 200 || $status >= 300) {
        throw new RuntimeException('HTTP ' . $status);
    }
    $user = parseUser($body);
    echo $user['id'] . ': ' . $user['name'] . PHP_EOL;
} finally {
    curl_close($curl);
}

Тот же запрос через Guzzle:

$client = new GuzzleHttp\Client([
    'base_uri' => 'http://127.0.0.1:8095/',
    'headers' => ['Accept' => 'application/json', 'X-Request-ID' => 'demo-001'],
    'connect_timeout' => 1.0,
    'timeout' => 2.0,
    'allow_redirects' => false,
    'http_errors' => false, // Статус проверяем так же, как в примере cURL.
    'proxy' => '',
]);
$response = $client->get('users/7', ['query' => $query]);
$status = $response->getStatusCode();
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP ' . $status);
}
$user = parseUser((string) $response->getBody());
echo $user['id'] . ': ' . $user['name'] . PHP_EOL;

В Guzzle URL, параметры, заголовки и ограничения собраны в одном объекте клиента и массиве запроса. Проверки полезных данных остаются необходимыми в обоих вариантах. Библиотека не знает, что ваш API обязан вернуть целочисленный id и строковый name.

Что выбрать? Нативный cURL удобен для небольшого автономного скрипта, специфических возможностей libcurl или проекта с готовой проверенной обёрткой. Guzzle удобен, когда запросов много: несколько методов API, общая авторизация, файлы, тесты, единая обработка ответов. Менять уже работающий код только ради названия библиотеки необязательно.

Документация: PHP: curl_exec и HTTP-коды.

3. Первый запрос: полный рабочий файл

В распакованном проекте откройте первый терминал и запустите учебный API. Оставьте это окно открытым:

php -S 127.0.0.1:8095 local-server.php

Сервер слушает только ваш компьютер. Маршрут /users/7 возвращает пользователя, /echo показывает принятые параметры, /upload принимает файл. Это учебные адреса из архива, а не универсальные маршруты любого API. Встроенный сервер PHP предназначен для локальной разработки.

Файл request.php целиком:

<?php
declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;

$client = new Client([
    'base_uri' => 'http://127.0.0.1:8095/',
    'connect_timeout' => 2.0,
    'timeout' => 5.0,
    'allow_redirects' => false,
    'proxy' => '', // Локальный стенд: не используем системный HTTP_PROXY.
    'headers' => ['Accept' => 'application/json'],
]);

try {
    $response = $client->get('users/7');
    $user = json_decode((string) $response->getBody(), true, 512, JSON_THROW_ON_ERROR);
    if (!is_array($user) || !isset($user['id'], $user['name'])
        || !is_int($user['id']) || !is_string($user['name'])) {
        throw new UnexpectedValueException('Ответ не соответствует ожидаемой структуре пользователя.');
    }
    echo $user['id'] . ': ' . $user['name'] . PHP_EOL;
} catch (GuzzleException $e) {
    fwrite(STDERR, 'Ошибка HTTP/сети: ' . $e->getMessage() . PHP_EOL);
    exit(1);
} catch (JsonException | UnexpectedValueException $e) {
    fwrite(STDERR, 'Ошибка данных: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

Во втором терминале, в той же папке, выполните:

composer request

Ожидаемый результат: 7: Александр. Эквивалентный запуск — php request.php. После практики остановите сервер сочетанием Ctrl + C в первом терминале.

Как пробовать следующие фрагменты. Сделайте копию request.php с именем experiment.php. Оставьте подключение автозагрузчика и создание $client, затем заменяйте всё содержимое блока try целиком выбранным фрагментом; существующие catch сохраняйте. Запускайте php experiment.php. Так исходный composer request продолжит работать. Если пример показывает собственный try/catch, замените соответствующий блок полностью. Параметр proxy отключает системный прокси только для учебного localhost.

4. Как удобно собирать запрос

У запроса четыре понятные части: метод → адрес → параметры → тело. Клиент хранит общие настройки, третий аргумент request() описывает конкретный вызов.

$response = $client->request('GET', 'echo', [
    'query' => [
        'search' => 'Иван Петров',
        'page' => 2,
        'limit' => 10,
    ],
    'headers' => ['X-Request-ID' => 'article-001'],
    'timeout' => 3.0,
]);

echo (string) $response->getBody();

Сервер вернёт method: GET и принятые query: имя с пробелом, страницу и лимит. Кодирование параметров выполняет библиотека — не нужно вручную склеивать ?search=... и &page=.... Числа в query на принимающей стороне обычно оказываются строками.

В этом вызове timeout=3 переопределяет общий timeout=5 только для одного запроса, а X-Request-ID дополняет клиентский Accept. Следующий вызов без этих опций снова использует общие настройки.

$client->get('echo', $options) — короткая запись $client->request('GET', 'echo', $options). Аналогично доступны post, put, patch, delete. Метод выбирается по контракту API: PATCH обычно меняет часть объекта, DELETE удаляет его, но конкретные пути и ответы определяет сервис.

Параметры можно собирать по условиям:

$filters = ['page' => 1, 'limit' => 20];
$search = trim('Иван');
if ($search !== '') {
    $filters['search'] = $search;
}
$response = $client->get('echo', ['query' => $filters]);

Ловушка с косой чертой. Для условного base_uri=https://api.example.test/v1/:

Начальная / заменяет путь от корня. Если в самой базе убрать последнюю / после v1, относительный путь тоже может заменить этот сегмент. Домен example.test здесь иллюстрирует правило и не является рабочим API. Абсолютный URL заменяет базу целиком: не подставляйте произвольный пользовательский URL в клиент с секретными заголовками.

Документация: Клиент и base_uri.

5. POST: JSON, форма или готовое тело

JSON. В json передавайте PHP-массив, а не уже закодированную строку:

$response = $client->post('echo', [
    'json' => [
        'name' => 'Александр',
        'email' => 'demo@example.test',
        'active' => true,
    ],
]);
echo (string) $response->getBody();

Локальный API вернёт объект в поле json. При обычных настройках Guzzle задаёт соответствующий Content-Type. Обратите внимание: Accept описывает желаемый ответ, Content-Type — отправляемое тело.

Форма. Тот же подход, но другой формат:

$response = $client->post('echo', [
    'form_params' => ['name' => 'Александр', 'city' => 'Москва'],
]);
echo (string) $response->getBody();

Теперь значения окажутся в поле form. Выбор между json и form_params определяет документация сервера.

$payload = json_encode(
    ['name' => 'Александр'],
    JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR
);
$response = $client->post('echo', [
    'headers' => ['Content-Type' => 'application/json'],
    'body' => $payload,
]);

6. Заголовки, авторизация и cookies

Общие заголовки задавайте в клиенте, специфичные — в конкретном вызове. Секретный токен храните в переменной окружения или хранилище секретов приложения. Ниже — самостоятельная настройка клиента для вашего настоящего HTTPS API; замените демонстрационный домен на доверенный адрес.

$token = getenv('API_TOKEN');
if ($token === false || $token === '') {
    throw new RuntimeException('Не задана переменная API_TOKEN.');
}
$api = new GuzzleHttp\Client([
    'base_uri' => 'https://api.example.test/v1/',
    'timeout' => 10.0,
    'allow_redirects' => false,
    'headers' => [
        'Accept' => 'application/json',
        'Authorization' => 'Bearer ' . $token,
    ],
]);
$response = $api->get('users/7');

Не помещайте токен в URL и не выводите целиком запросы, исключения или debug-трассировку в публичную страницу. Ошибка может содержать адрес и фрагмент ответа. Пример request.php печатает детали в локальный терминал; в приложении пользователю достаточно понятного сообщения, а разработчику — очищенной записи в журнале.

7. Ответ: статус, заголовки, JSON

$response = $client->get('users/7');
$status = $response->getStatusCode();
$contentType = $response->getHeaderLine('Content-Type');
$body = (string) $response->getBody();
$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

echo $status . PHP_EOL;
echo $contentType . PHP_EOL;
echo $data['name'] . PHP_EOL;

Для нашего маршрута получите 200, JSON Content-Type и имя. Объект ответа соответствует PSR-7, а тело представляет собой поток. getContents() читает оставшуюся часть от текущей позиции; после чтения она может быть пустой. Для небольшого JSON удобно один раз получить строку и работать с ней. Для больших файлов используйте sink.

Проверяйте три уровня. HTTP-статус говорит, как сервер обработал запрос. json_decode(..., JSON_THROW_ON_ERROR) проверяет синтаксис JSON. Проверка полей и типов подтверждает пригодность данных для вашей задачи — она показана в полном request.php. JSON {"error":"..."} с HTTP 200 вполне может быть бизнес-ошибкой по правилам конкретного API.

Ответ 204 обычно не содержит тела: не пытайтесь декодировать пустую строку как JSON. Сначала обработайте этот статус, если он предусмотрен контрактом вашего метода.

Документация: Ответы и потоки PSR-7.

Документация: PHP: json_decode.

8. Исключения: сеть, HTTP и данные

Ниже — альтернативный блок try/catch для уже созданного $client. Маршрут status/404 специально отвечает ошибкой. Более конкретные исключения ставьте раньше общих.

try {
    $response = $client->get('status/404');
    $data = json_decode((string) $response->getBody(), true, 512, JSON_THROW_ON_ERROR);
} catch (GuzzleHttp\Exception\ConnectException $e) {
    echo 'Не удалось установить соединение.';
} catch (GuzzleHttp\Exception\RequestException $e) {
    $response = $e->getResponse();
    echo $response === null
        ? 'Ошибка запроса без HTTP-ответа.'
        : 'Сервер вернул HTTP ' . $response->getStatusCode();
} catch (GuzzleHttp\Exception\GuzzleException $e) {
    echo 'Другая ошибка выполнения HTTP-запроса.';
} catch (JsonException $e) {
    echo 'Ответ не является корректным JSON.';
}

Для этого вызова результат — Сервер вернул HTTP 404. ClientException для 4xx и ServerException для 5xx наследуются от RequestException. ConnectException в эту ветку не входит, поэтому один catch (RequestException) не покрывает все сетевые отказы.

Если 404 — ожидаемый результат поиска, можно получать ответ без исключения:

$response = $client->get('status/404', ['http_errors' => false]);
$status = $response->getStatusCode();
if ($status === 404) {
    echo 'Пользователь не найден.';
} elseif ($status < 200 || $status >= 300) {
    throw new RuntimeException('Неожиданный HTTP ' . $status);
}

http_errors=false меняет реакцию на HTTP-код, но не устраняет сетевые ошибки. Этот вызов всё равно размещайте внутри обработчика ошибок транспорта.

9. Таймауты, HTTPS и перенаправления

Задавайте лимиты осознанно: приложение не должно бесконечно ждать сторонний сервис. В учебном клиенте timeout=5 ограничивает время запроса, connect_timeout=2 — установление соединения. Поддержка connect_timeout зависит от транспорта; встроенный cURL handler его поддерживает.

Воспроизведите настоящий timeout: локальный /slow ждёт 0,4 секунды, а клиенту даём 0,1 секунды.

try {
    $client->get('slow', ['timeout' => 0.1]);
} catch (GuzzleHttp\Exception\GuzzleException $e) {
    echo 'Запрос не завершился в отведённое время.';
}

Это демонстрация с заранее известной задержкой. В обычном приложении такой общий catch не доказывает, что причиной был timeout: проверяйте класс, диагностический контекст и журнал. Стадия сбоя и handler влияют на тип исключения.

• HTTPS: оставляйте проверку сертификатов включённой. При ошибке сертификата исправьте цепочку CA или настройку окружения; verify=false не является рабочим исправлением.
• Перенаправления: для API с известным адресом удобно явно поставить allow_redirects=false и разобраться с 3xx. Если разрешаете переходы, задайте допустимые протоколы и предел.
• Прокси: настройки окружения могут менять путь запроса. В локальном стенде он отключён; в корпоративной сети используйте согласованные настройки.

Документация: Опции запросов: timeout, verify, redirects.

10. Отправка и скачивание файлов

Отправка multipart. В архиве есть fixtures/note.txt. Фрагмент открывает его как поток и отправляет вместе с обычным полем:

$file = fopen(__DIR__ . '/fixtures/note.txt', 'rb');
if ($file === false) {
    throw new RuntimeException('Не удалось открыть файл.');
}
try {
    $response = $client->post('upload', [
        'multipart' => [
            ['name' => 'file', 'contents' => $file, 'filename' => 'upload.txt'],
            ['name' => 'description', 'contents' => 'Учебный документ'],
        ],
    ]);
    echo (string) $response->getBody();
} finally {
    if (is_resource($file)) {
        fclose($file);
    }
}

Сервер вернёт имя, размер и код загрузки; error=0 означает успешный приём PHP. Не задавайте вручную Content-Type: multipart/form-data: библиотека должна добавить правильную границу частей.

Скачивание. sink записывает тело в файл, не требуя сначала собрать весь ответ в строку. Временный файл нужен, чтобы проверить результат перед дальнейшим использованием:

$path = tempnam(sys_get_temp_dir(), 'guzzle-');
if ($path === false) {
    throw new RuntimeException('Не удалось создать временный файл.');
}
try {
    $response = $client->get('file', ['sink' => $path]);
    if ($response->getStatusCode() !== 200) {
        throw new RuntimeException('Неожиданный статус загрузки.');
    }
    echo file_get_contents($path); // Только маленький учебный файл.
} finally {
    if (is_file($path)) {
        unlink($path);
    }
}

Результат: Guzzle download demo. В рабочем приложении после проверки статуса, типа и допустимого размера переместите файл в своё хранилище. Даже ошибочный ответ или оборванная передача могут оставить данные на диске — само наличие файла ещё не подтверждает успех.

11. Несколько запросов: async и Pool

Если запросы независимы, их можно запустить до ожидания результата. Utils::settle() позволяет получить итоги всей группы, включая отказы. Следующий фрагмент выполняется с нашим локальным клиентом:

$promises = [
    'user' => $client->getAsync('users/7'),
    'missing' => $client->getAsync('status/404'),
];
$results = GuzzleHttp\Promise\Utils::settle($promises)->wait();

foreach ($results as $name => $result) {
    if ($result['state'] === 'fulfilled') {
        echo $name . ': HTTP ' . $result['value']->getStatusCode() . PHP_EOL;
    } else {
        echo $name . ': запрос завершился ошибкой' . PHP_EOL;
    }
}

Будет успешный user: HTTP 200 и отказ missing. wait() дожидается завершения группы. Для большого списка используйте ограничение числа запросов:

$requests = function () use ($client) {
    foreach (range(1, 10) as $number) {
        yield function () use ($client, $number) {
            return $client->getAsync('echo', ['query' => ['number' => $number]]);
        };
    }
};
$pool = new GuzzleHttp\Pool($client, $requests(), [
    'concurrency' => 3,
    'fulfilled' => function ($response, $index): void {
        echo $index . ': HTTP ' . $response->getStatusCode() . PHP_EOL;
    },
    'rejected' => function ($reason, $index): void {
        echo $index . ': ошибка запроса' . PHP_EOL;
    },
]);
$pool->promise()->wait();

Здесь одновременно допускается до трёх незавершённых операций. Реальная параллельность зависит от handler и сервера. Однопоточный учебный php -S и MockHandler не подходят для вывода «стало в N раз быстрее». Ограничение concurrency также не заменяет соблюдение лимита запросов в секунду у поставщика API.

Документация: Promises и Pool.

12. Повторы, журнал и устройство клиента

Guzzle даёт механизм middleware — обработчиков вокруг отправки запроса. Через них удобно организовать журнал, измерение времени и повторные попытки. Обычный клиент не означает автоматическую безопасную политику retry для вашего API.

• Ограничьте число повторов и общее время выполнения.
• Повторяйте только подходящие временные отказы, учитывая договорённости сервиса и Retry-After.
• Для чтения повтор обычно проще; создание заказа через POST требует идемпотентного ключа или другого механизма API. Потерянный ответ не доказывает, что сервер не выполнил операцию.
• Записывайте метод, разрешённый путь, статус, длительность и идентификатор запроса. Исключайте токены, cookies и чувствительное тело.

Для большого приложения вынесите вызовы в отдельный класс, например UserApi, и передавайте ему HTTP-клиент через конструктор. Тогда контроллер работает с понятным findUser($id), а URL, форматы и обработка сетевых ошибок остаются в одном месте. Для теста можно подставить клиент с MockHandler.

Документация: Handlers и middleware.

13. Готовый проект: 12 сценариев и живой HTTP

Скачать примеры Guzzle — ZIP

В архиве исходники, fixtures, README, composer.json и composer.lock. Два режима дополняют друг друга: mock-сценарии проверяют формирование запросов и обработку заданных ответов, локальный сервер позволяет действительно отправить HTTP, передать файл и дождаться таймаута.

composer demo -- list
composer demo -- get
composer demo -- all

Настоящие HTTP-проверки. При запущенном в первом терминале сервере выполните во втором:

composer request
composer compare
composer live

compare запускает одинаковые вызовы через нативный cURL и Guzzle; live проверяет реальную работу учебных маршрутов. Подробный порядок и ожидаемые результаты приведены в README.

Проверено 6 ноября 2026 года: PHP 8.3.33, Composer 2.10.3, Guzzle 7.16.1, Windows и расширение cURL. В архивном проекте прошли 12 из 12 mock-сценариев и 10 из 10 локальных HTTP-проверок, включая multipart, скачивание, HTTP-ошибки и настоящий timeout. Отдельно выполнены запросы из сравнения cURL/Guzzle и применимые PHP-фрагменты статьи, включая JSON, форму, собственное тело, async и Pool. Синтаксис PHP-фрагментов проверен. Пример Bearer-авторизации с демонстрационным доменом проверен только синтаксически — внешнему сервису запрос не отправлялся.

Установленные зависимости прошли composer validate --strict, composer check-platform-reqs и composer audit --locked; известных advisories на момент проверки не обнаружено. Другие версии PHP, внешний DNS, HTTPS/TLS, отдельный таймаут соединения и ускорение параллельных запросов этим стендом не проверялись.

Документация: MockHandler и история запросов.

14. Шпаргалка и частые ошибки

Полезные команды диагностики окружения:

php --version
php --ini
php --ri curl
composer diagnose
composer check-platform-reqs
composer audit

15. Источники и следующий шаг

• Официальная документация Guzzle 7 — установка, запросы, опции и примеры.
• PHP: расширение cURL — функции и параметры libcurl.
• PSR-7 и PSR-18 — HTTP-сообщения и контракт клиента.
• Composer в PHP: от первой команды до рабочего проекта — зависимости, lock-файл, автозагрузка и команды.
• Архив примеров этой статьи — практика, которую можно повторить локально.

Для закрепления поменяйте фильтры в GET, отправьте свой небольшой JSON и обработайте ожидаемый 404. Затем перенесите один метод настоящего API в отдельный класс с понятным результатом и обработкой ошибок. Такой переход хорошо показывает, зачем нужен единый HTTP-клиент.