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
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
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.
// Эти параметры заменяют тело и заголовки из примера 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 получит несколько блоков, поэтому пример очищает массив на каждой строке статуса и сохраняет заголовки последнего блока.
$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
- Для GET соберите параметры через
http_build_query(). Для POST выберите JSON, обычную форму или multipart по контракту API. - Передайте подходящие заголовки
Accept,Content-Typeи, при необходимости,Authorization. - Включите
CURLOPT_RETURNTRANSFER, задайте тайм-ауты подключения и всей операции, оставьте проверку TLS включённой. - Проверьте
curl_exec() === false, затем HTTP-статус. Разбирайте JSON сJSON_THROW_ON_ERRORи проверяйте ожидаемые поля. - При
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.