PHPTime

cURL в PHP: GET и POST запросы, заголовки, JSON API

Расширение cURL позволяет PHP обращаться к HTTP API и управлять методом запроса, заголовками, телом и тайм-аутами. На примерах GET и POST разберём, как кодировать данные, проверять статус ответа и отличать ошибки сети от ошибок API.

Как работает cURL в PHP

Расширение curl использует библиотеку libcurl. В PHP вызов curl_init() создаёт объект CurlHandle, curl_setopt_array() задаёт параметры, а curl_exec() выполняет запрос. Если включить CURLOPT_RETURNTRANSFER, тело ответа вернётся строкой. Без этой настройки cURL выводит тело напрямую, а успешный вызов возвращает true.

Команда php -m показывает модули для CLI. Если запрос запускается через PHP-FPM, проверьте расширение и там: у CLI и веб-приложения могут быть разные конфигурации. В коде наличие модуля проверяется через extension_loaded('curl').

В примерах адрес HTTPS-эндпоинта берётся из переменной окружения API_ENDPOINT, а токен, где он нужен, из API_TOKEN. Подставьте адрес своего API и согласуйте с его документацией поля запроса. Каждый пример, кроме фрагментов отправки формы и чтения заголовков, можно запустить отдельным PHP-файлом.

GET-запрос в PHP через cURL

В GET-запросе параметры фильтрации и пагинации обычно передают в строке запроса. Соберите её через http_build_query(): функция закодирует пробелы, кириллицу и символы, которые иначе могли бы изменить смысл параметров. Для GET в cURL достаточно нового дескриптора, но CURLOPT_HTTPGET позволяет указать метод явно.

PHP
<?php
declare(strict_types=1);

$endpoint = getenv('API_ENDPOINT');
if ($endpoint === false || $endpoint === '') {
    throw new RuntimeException('Задайте API_ENDPOINT');
}

// В этом примере адрес эндпоинта задан без query-параметров и фрагмента.
$query = http_build_query(
    ['q' => 'PHP cURL', 'page' => 1, 'limit' => 10],
    '',
    '&',
    PHP_QUERY_RFC3986,
);

$ch = curl_init($endpoint . '?' . $query);
if ($ch === false) {
    throw new RuntimeException('Не удалось создать дескриптор cURL');
}

if (!curl_setopt_array($ch, [
    CURLOPT_HTTPGET => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 3,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Accept: application/json'],
])) {
    throw new RuntimeException('Не удалось настроить GET-запрос');
}

$body = curl_exec($ch);
if ($body === false) {
    throw new RuntimeException(sprintf('cURL %d: %s', curl_errno($ch), curl_error($ch)));
}

$status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP ' . $status);
}

// В CLI выводим тело ответа. В приложении передайте его обработчику.
echo $body, PHP_EOL;

Флаг PHP_QUERY_RFC3986 кодирует пробел как %20. Если адрес уже содержит параметры, добавляйте новые через & перед фрагментом или собирайте адрес средствами HTTP-клиента. Кодирование отдельных значений и кодирование полной строки запроса дают разные результаты: повторное кодирование превратит %20 в %2520.

POST-запрос в PHP с JSON

Для POST с JSON сериализуйте массив через json_encode() и передайте полученную строку в CURLOPT_POSTFIELDS. Заголовок Content-Type сообщает серверу формат тела запроса. Accept сообщает, какой формат ответа нужен клиенту. Сервер может вернуть пустое тело, например при статусе 204 No Content.

PHP
<?php
declare(strict_types=1);

$endpoint = getenv('API_ENDPOINT');
$token = getenv('API_TOKEN');
if ($endpoint === false || $endpoint === '' || $token === false || $token === '') {
    throw new RuntimeException('Задайте API_ENDPOINT и API_TOKEN');
}

// JSON_THROW_ON_ERROR поднимет исключение, если данные нельзя сериализовать.
$payload = json_encode(
    ['name' => 'Тестовая запись', 'active' => true],
    JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE,
);

$ch = curl_init($endpoint);
if ($ch === false) {
    throw new RuntimeException('Не удалось создать дескриптор cURL');
}

if (!curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 3,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Accept: application/json',
        'Authorization: Bearer ' . $token,
    ],
])) {
    throw new RuntimeException('Не удалось настроить POST-запрос');
}

$body = curl_exec($ch);
if ($body === false) {
    throw new RuntimeException(sprintf('cURL %d: %s', curl_errno($ch), curl_error($ch)));
}

$status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP ' . $status);
}

if ($status !== 204 && $body !== '') {
    // true преобразует JSON-объекты в ассоциативные массивы.
    $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    var_export($result);
}

Если API обещает JSON при конкретном статусе, проверяйте также структуру результата. Корректный JSON может содержать null, число или строку. Когда контракт обещает объект с полем id, проверьте тип результата и само поле. Если пустое тело допустимо только для 204, обрабатывайте пустой ответ с 200 как нарушение контракта.

POST с полями формы и файлами

Формат телаЧто передать в CURLOPT_POSTFIELDS
application/jsonСтроку из json_encode() и заголовок Content-Type: application/json.
application/x-www-form-urlencodedСтроку из http_build_query(). Формат можно явно указать в Content-Type.
multipart/form-dataМассив полей. Для файла используйте CURLFile. cURL сформирует заголовок с разделителем частей.

Чтобы отправить обычную форму, замените сериализацию и заголовки в примере POST. При загрузке файла используйте массив наподобие ['file' => new CURLFile($path)] и уберите прежний Content-Type, чтобы cURL добавил корректный параметр boundary.

PHP
// Эти параметры заменяют тело и заголовки из примера POST.
CURLOPT_POSTFIELDS => http_build_query(['name' => 'Тестовая запись']),
CURLOPT_HTTPHEADER => [
    'Content-Type: application/x-www-form-urlencoded',
    'Accept: application/json',
    'Authorization: Bearer ' . $token,
],

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

В CURLOPT_HTTPHEADER передаётся массив строк формата Имя: значение. Передавайте токен в заголовке Authorization и храните его в конфигурации приложения. Обычно Content-Length вычисляет сам cURL.

Чтобы получить отдельные заголовки ответа, установите CURLOPT_HEADERFUNCTION до вызова curl_exec(). Обработчик получает по одной строке и должен возвращать её длину в байтах. При промежуточном ответе вроде 100 Continue callback получит несколько блоков, поэтому пример очищает массив на каждой строке статуса и сохраняет заголовки последнего блока.

PHP
$responseHeaders = [];
if (!curl_setopt(
    $ch,
    CURLOPT_HEADERFUNCTION,
    static function (CurlHandle $handle, string $line) use (&$responseHeaders): int {
        if (str_starts_with($line, 'HTTP/')) {
            $responseHeaders = [];
        } elseif (($separator = strpos($line, ':')) !== false) {
            // Имена заголовков регистронезависимы. Повторы сохраняем.
            $name = strtolower(trim(substr($line, 0, $separator)));
            $responseHeaders[$name][] = trim(substr($line, $separator + 1));
        }

        return strlen($line);
    },
)) {
    throw new RuntimeException('Не удалось настроить чтение заголовков');
}

После curl_exec() значение $responseHeaders['retry-after'][0] ?? null даст первый заголовок Retry-After, если сервер его прислал. Опция CURLOPT_HEADER добавляет сырые заголовки прямо к телу при CURLOPT_RETURNTRANSFER. Оставьте её выключенной, если передаёте тело в json_decode().

Ошибки при работе с HTTP API на PHP

  • curl_exec() вернул false. Прочитайте curl_errno() и curl_error() сразу после вызова. Возможные причины — ошибка DNS, сбой соединения, истечение тайм-аута или проблема с TLS. Используйте строгое сравнение === false: пустая строка и строка 0 тоже могут быть телом успешного ответа.
  • Сервер вернул ошибку HTTP. По умолчанию curl_exec() может вернуть тело и при 400, 404 или 500. Читайте статус через CURLINFO_RESPONSE_CODE. Если API присылает код ошибки в JSON, оставьте CURLOPT_FAILONERROR выключенной, чтобы тело оставалось доступно.
  • Сервер вернул HTML или невалидный JSON. Такое бывает у прокси, страниц авторизации и неверных маршрутов. Проверьте HTTP-статус и заголовок Content-Type. Флаг JSON_THROW_ON_ERROR позволяет обработать ошибку разбора через JsonException.
  • Сервер отвечает 415 Unsupported Media Type. Сверьте формат тела с Content-Type. Частая причина — массив в CURLOPT_POSTFIELDS при объявленном application/json.
  • Запрос долго висит или обрывается. CURLOPT_CONNECTTIMEOUT ограничивает этап установления соединения, а CURLOPT_TIMEOUT — всю операцию. При тайм-ауте POST сервер мог успеть принять запрос. Для повторов операции создания используйте ключ идемпотентности, если API его поддерживает.

При ошибке проверки TLS проверьте системное хранилище доверенных сертификатов и настройки PHP окружения. При необходимости укажите актуальный файл сертификатов через curl.cainfo или CURLOPT_CAINFO. Сохраняйте проверку сертификата и имени сервера включённой. В логи полезно записывать HTTP-статус, номер ошибки cURL и идентификатор запроса, если API его возвращает. Токен и тело с персональными данными в лог передавать не нужно.

Отличия cURL в PHP 8.3, 8.4 и 8.5

Базовые GET- и POST-запросы из примеров одинаково пишутся для PHP 8.3–8.5. Начиная с PHP 8.0, дескриптор cURL — объект CurlHandle. В старом коде встречается проверка is_resource($ch). В PHP 8.x проверяйте результат curl_init() на false, а для функций, принимающих готовый дескриптор, используйте тип CurlHandle.

В PHP 8.3 и 8.4 curl_close() уже не освобождает объект, а в PHP 8.5 эта функция объявлена устаревшей. Дескриптор освобождается, когда исчезает последняя ссылка на него. В короткой функции достаточно локальной переменной. В долгоживущем процессе unset($ch) удаляет конкретную ссылку, если дескриптор больше не нужен.

Версия PHP и версия libcurl — разные вещи. Например, доступность HTTP/2 зависит от сборки libcurl. Чтобы выяснить, какой библиотекой пользуется PHP и какие возможности она предоставляет, смотрите результат curl_version() в том окружении, где выполняются запросы.

Чек-лист перед вызовом API

  1. Для GET соберите параметры через http_build_query(). Для POST выберите JSON, обычную форму или multipart по контракту API.
  2. Передайте подходящие заголовки Accept, Content-Type и, при необходимости, Authorization.
  3. Включите CURLOPT_RETURNTRANSFER, задайте тайм-ауты подключения и всей операции, оставьте проверку TLS включённой.
  4. Проверьте curl_exec() === false, затем HTTP-статус. Разбирайте JSON с JSON_THROW_ON_ERROR и проверяйте ожидаемые поля.
  5. При 429 учитывайте Retry-After и правила API. Перед повтором POST проверьте, как API предотвращает дубли.

Частые вопросы

Как отправить GET-запрос через cURL в PHP?

Соберите параметры через http_build_query(), добавьте их к адресу, включите CURLOPT_RETURNTRANSFER и вызовите curl_exec(). Затем проверьте результат на false и получите HTTP-статус через CURLINFO_RESPONSE_CODE.

Как отправить POST-запрос с JSON в PHP?

Сериализуйте данные через json_encode() с флагом JSON_THROW_ON_ERROR. Включите CURLOPT_POST, передайте строку в CURLOPT_POSTFIELDS и задайте заголовок Content-Type: application/json.

Почему cURL возвращает тело ответа при HTTP 404?

При выключенной CURLOPT_FAILONERROR cURL считает обмен завершённым и возвращает тело, даже если сервер прислал статус 404. Ошибку HTTP определяйте через CURLINFO_RESPONSE_CODE, а сбой cURL — через строгое сравнение результата curl_exec() с false.

Справка по теме

Ещё в разделе «Справочник PHP»

Ассоциативные и многомерные массивы в PHP

Как создавать ассоциативные и многомерные массивы в PHP, читать вложенные данные, получать ключи и значения через array_keys() и array_values().

10 мин

Вывод ошибок в PHP: display_errors, error_reporting и логи

Как включить вывод ошибок PHP через display_errors и ini_set, настроить error_reporting и error_log, найти логи и разобраться с deprecated в PHP 8.3–8.5.

9 мин

Дата и время в PHP: date, DateTime и часовые пояса

Как получить текущую дату и время в PHP, настроить часовой пояс, разобрать строку и отформатировать дату с date(), strtotime() и DateTimeImmutable.

8 мин

Загрузка файлов на сервер в PHP: $_FILES и безопасность

Как принять файл через $_FILES, проверить размер, MIME-тип и расширение, сохранить его вне публичной папки, выдать на скачивание и обработать ZIP.

10 мин