Расширение cURL позволяет PHP-приложению обращаться к HTTP API. С его помощью можно запросить остатки товаров, отправить заявку или получить статус доставки. Для такой интеграции нужны две проверки: состоялся ли сетевой обмен и какой статус вернул сервер.
В статье соберём функцию для GET и JSON POST. Она ограничивает время запроса, передаёт токен через заголовок и возвращает статус отдельно от тела. GET, POST с тестовым токеном, HTTP 429 и таймаут проверены на локальном сервере. Для запуска в проекте используйте поддерживаемую версию PHP с расширением curl.
Подготовьте адрес API и параметры
Убедитесь, что расширение загружено командой php --ri curl. Если PHP работает через веб-сервер, проверьте также его конфигурацию: командная строка и PHP-FPM могут читать разные файлы настроек. В документации API найдите базовый HTTPS-адрес, путь, метод, требования к авторизации и формат ответа.
В примере ниже адрес использует зарезервированный домен api.example.com. Подставьте адрес своего API и проверьте ожидаемые имена полей. Базовый адрес храните в конфигурации. Если форма принимает номер заказа или фильтр, подставляйте это значение в заранее заданный путь или параметры. Для прямого запроса по адресу, выбранному посетителем, нужна отдельная проверка назначения.
Общая функция для GET и JSON POST
function requestJson(string $url, ?array $payload = null, ?string $token = null): array
{
$headers = ['Accept: application/json'];
$options = [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT_MS => 2000,
CURLOPT_TIMEOUT_MS => 5000,
CURLOPT_FOLLOWLOCATION => false,
];
if ($payload !== null) {
$headers[] = 'Content-Type: application/json';
$options[CURLOPT_POST] = true;
$options[CURLOPT_POSTFIELDS] = json_encode($payload, JSON_THROW_ON_ERROR);
}
if ($token !== null) {
$headers[] = 'Authorization: Bearer ' . $token;
}
$options[CURLOPT_HTTPHEADER] = $headers;
$handle = curl_init($url);
if ($handle === false) {
throw new RuntimeException('Не удалось создать cURL-сеанс');
}
try {
if (!curl_setopt_array($handle, $options)) {
throw new RuntimeException('Не удалось настроить cURL-сеанс');
}
$body = curl_exec($handle);
if ($body === false) {
throw new RuntimeException('Ошибка транспорта cURL: ' . curl_errno($handle));
}
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
return ['status' => $status, 'body' => $body];
} finally {
unset($handle);
}
}
Вызов без массива создаёт GET. Массив превращается в строку JSON и отправляется в POST. Обратите внимание на тип значения CURLOPT_POSTFIELDS: передача массива напрямую обычно даёт multipart-запрос, поэтому для JSON сначала нужен json_encode(). Флаг JSON_THROW_ON_ERROR позволяет поймать ошибку кодирования до отправки.
CURLOPT_RETURNTRANSFER возвращает тело в переменную. Сравнение с false выполняется строго, чтобы не спутать сбой с пустым результатом или строкой 0. Переходы по редиректам в примере отключены. Ответ 3xx остаётся виден вызывающему коду, который может свериться с документированным адресом. Проверка TLS используется с настройками по умолчанию.
GET: передавайте фильтры в строке запроса
$baseUrl = 'https://api.example.com';
$query = http_build_query(
['limit' => 2, 'search' => 'белый чай'],
'',
'&',
PHP_QUERY_RFC3986
);
$result = requestJson($baseUrl . '/items?' . $query);
http_build_query() кодирует пробелы, кириллицу и служебные символы. Это важно, когда значение пришло из формы: амперсанд внутри поисковой фразы должен остаться частью значения. Передайте пагинацию в виде параметров из документации. Для первого запроса задайте небольшой лимит и проверьте, в каком поле сервер возвращает массив результатов.
POST: отправляйте JSON и токен отдельно
$token = getenv('SHOP_API_TOKEN');
if ($token === false || trim($token) === '') {
throw new RuntimeException('Переменная SHOP_API_TOKEN не задана');
}
$result = requestJson(
$baseUrl . '/items',
['name' => 'Белый чай', 'quantity' => 2],
$token
);
Переменная окружения в примере задаётся при запуске приложения или в конфигурации хостинга. В репозитории достаточно сохранить имя переменной в примере конфигурации. Доступ к секрету выдавайте только процессу, которому он нужен. Если токен случайно попал в вывод отладки или в историю Git, отзовите его и замените.
Заголовок Accept сообщает серверу желаемый формат ответа. Content-Type описывает формат отправляемого тела. Даже при этих заголовках прокси или шлюз может вернуть HTML вместо ожидаемого JSON. Поэтому декодируйте тело после проверки статуса и обрабатывайте JsonException отдельно.
Разберите статус перед декодированием
if ($result['status'] < 200 || $result['status'] >= 300) {
throw new RuntimeException('API вернул HTTP ' . $result['status']);
}
if ($result['body'] === '') {
$data = null; // Например, HTTP 204.
} else {
$data = json_decode($result['body'], true, 512, JSON_THROW_ON_ERROR);
}
Этот фрагмент показывает общий порядок. В рабочем обработчике сверяйтесь с контрактом API: где-то пустое тело допустимо только при 204, а в другом случае 200 без ожидаемого поля означает нарушение контракта. Код 202 может означать, что сервер принял работу в очередь. Для такого ответа ищите идентификатор задачи и правила проверки её статуса.
| Что видит PHP | Что это значит | Что проверить |
|---|---|---|
curl_exec() === false | Сетевой обмен не завершился успешно | Номер ошибки cURL, DNS, соединение, сертификаты, время ожидания |
| HTTP 401 или 403 | Сервер ответил, но ограничил доступ | Токен, срок действия, права и требуемый способ авторизации |
| HTTP 429 | Сработало ограничение на запросы | Документацию лимита и заголовок Retry-After, если он есть |
| HTTP 5xx | Сервер или промежуточный шлюз сообщил об ошибке | Статус провайдера, идентификатор запроса и допустимость повтора |
| HTTP 2xx, но JSON не читается | Формат фактического тела отличается от ожидаемого | Тип содержимого и контракт конечной точки |
Подробнее об ограничениях частоты читайте в разборе ошибки 429. Чтобы соблюдать Retry-After, клиенту понадобится отдельно читать заголовки ответа: учебная функция сохраняет только статус и тело.
Два таймаута и одно решение о повторе
В функции соединение ограничено двумя секундами, а весь обмен — пятью. Лимит соединения охватывает установление связи, включая разрешение имени и согласование протоколов. Общий предел включает этот этап и передачу данных. Для короткой операции из веб-формы и пакетного запроса допустимое время может сильно различаться. Подбирайте оба значения по времени ответа API и бюджету времени родительской операции.
После таймаута POST сервер мог успеть создать запись, даже если PHP не дождался ответа. Перед повтором проверьте состояние операции по идентификатору или используйте документированный ключ идемпотентности, если API его поддерживает. Для повторяемых запросов ограничьте число попыток и учитывайте паузы. Немедленный повтор при каждом 429 может дополнительно увеличить нагрузку.
Что записывать в журнал
Для диагностики обычно хватает названия интеграции, метода, шаблона пути, статуса HTTP, номера ошибки cURL и длительности. Если API присылает безопасный идентификатор запроса, сохраните и его. Не выводите заголовок Authorization, полный URL с параметрами или сырое тело запроса и ответа: там могут оказаться ключи, персональные данные и сведения о заказах.
При ошибке проверки сертификата проверьте системное время, доверенные корневые сертификаты и совпадение имени узла. Исправьте конфигурацию доверия, сохранив проверку TLS. Для системной настройки журналов пригодится материал про мониторинг ошибок PHP.
Частые вопросы
Преобразуйте массив в JSON через json_encode, передайте строку в CURLOPT_POSTFIELDS и задайте Content-Type: application/json.
По умолчанию HTTP-ответ с ошибкой считается завершённым обменом. Проверьте код через curl_getinfo и CURLINFO_HTTP_CODE.
Первый ограничивает установление связи. Общий таймаут включает соединение, ожидание и передачу данных.
В хранилище секретов или конфигурации окружения. Передавайте токен в заголовке Authorization и убирайте его из журналов.
Источники
- 1.PHP: curl_exechttps://www.php.net/manual/en/function.curl-exec.php
- 2.PHP: curl_getinfohttps://www.php.net/manual/en/function.curl-getinfo.php
- 3.PHP: настройки curl_setopthttps://www.php.net/manual/en/function.curl-setopt.php
- 4.PHP: кодирование JSONhttps://www.php.net/manual/en/function.json-encode.php
- 5.PHP: построение строки запросаhttps://www.php.net/manual/en/function.http-build-query.php



