{
  "index": 356,
  "slug": "editorial-2018-02-mechanism-php-diagnostics",
  "title": "PHP и cURL: как доказать, что интеграция действительно сработала",
  "excerpt": "Строка от curl_exec() доказывает только получение ответа. Разбираем транспорт, HTTP-статус и контракт тела, чтобы не принять 403 или неверный JSON за успешную операцию.",
  "contentHtml": "<p>Ночной обмен заказами завершился без исключения. Утром в локальной базе нет новых записей. В журнале стоит только «запрос выполнен»: <code>curl_exec()</code> вернул строку. Позже выясняется, что строкой была HTML-страница с кодом 403. Код принял ответ сервера за результат операции. Цена ошибки — потерянная запись, повторная ручная обработка и риск отправить один заказ дважды.</p>\n<p>Тезис простой: успешный вызов cURL не равен успешной интеграции. Нужно последовательно подтвердить три факта: передача состоялась, сервер вернул допустимый HTTP-статус, а тело соответствует договору. Каждый факт проверяет свой слой. Если пропустить один слой, диагностика превращается в догадку.</p>\n<h2>Что именно сообщает curl_exec()</h2>\n<p>При включённом <code>CURLOPT_RETURNTRANSFER</code> функция возвращает тело ответа, если cURL завершил передачу, и <code>false</code>, если произошла ошибка cURL. Значение <code>false</code> означает проблему транспорта: например, DNS, таймаут или TLS. Оно не описывает ответ приложения партнёра.</p>\n<p>HTTP 401, 404 или 500 обычно не становятся ошибкой cURL. Сервер успел ответить, поэтому функция возвращает тело. Статус нужно читать отдельно через <code>curl_getinfo()</code>. Проверка <code>if ($body)</code> смешивает ещё больше случаев: пустую строку, строку <code>\"0\"</code> и <code>false</code>. Используйте строгое сравнение с <code>false</code>.</p>\n<p>После статуса остаётся третий вопрос: что лежит в теле. Код 200 может содержать ожидаемый JSON, ошибочный JSON, HTML прокси или корректный JSON без обязательного идентификатора. Протокол завершился, но бизнес-операция ещё не доказана.</p>\n<figure><img src=\"/assets/editorial/2018/curl-outcome-classifier.svg\" alt=\"Схема диагностики cURL: ошибка передачи, проверка HTTP-статуса и проверка контракта тела\" /><figcaption>Строка от <code>curl_exec()</code> подтверждает получение ответа. Она не подтверждает успех HTTP-запроса и операции.</figcaption></figure>\n<h2>Симптом → причина → проверка → действие</h2>\n<div class=\"table-scroll\"><table><thead><tr><th scope=\"col\">Симптом</th><th scope=\"col\">Причина</th><th scope=\"col\">Проверка</th><th scope=\"col\">Действие</th></tr></thead><tbody><tr><td><code>curl_exec()</code> вернул <code>false</code></td><td>Передача не завершилась</td><td><code>curl_errno()</code>, <code>curl_error()</code>, время и адрес хоста</td><td>Проверить DNS, таймаут, TLS и доступность сервиса</td></tr><tr><td>Есть тело, статус 401 или 403</td><td>Нет прав или истекли учётные данные</td><td><code>http_code</code>, имя операции и request ID</td><td>Проверить токен и область доступа; не печатать секрет</td></tr><tr><td>Есть тело, статус 404</td><td>Неверен маршрут или версия API</td><td>Метод, нормализованный путь и версию endpoint</td><td>Сверить URL с договором партнёра</td></tr><tr><td>Есть тело, статус 500</td><td>Ошибка на удалённой стороне</td><td>Статус, время, request ID и размер тела</td><td>Передать партнёру идентификатор; не повторять запись вслепую</td></tr><tr><td>Статус 2xx, но поле результата отсутствует</td><td>Нарушен контракт полезной нагрузки</td><td>Тип тела, JSON-ошибка и обязательные поля</td><td>Отклонить ответ и открыть разбор контракта</td></tr><tr><td>Таймаут после POST</td><td>Результат операции неизвестен</td><td>Идемпотентный ключ или запрос статуса операции</td><td>Не отправлять тот же POST автоматически без гарантии</td></tr></tbody></table></div>\n<h2>Минимальный клиент с раздельными ошибками</h2>\n<p>Ниже учебный пример для PHP с cURL. Он не задаёт универсальные таймауты и не заменяет правила конкретного API. Его задача — показать границы классификации. Для production-кода добавьте лимит размера ответа, нужный метод, авторизацию и логгер проекта.</p>\n<pre><code>&lt;?php\n\nfunction requestPartner($url, $requestId)\n{\n    $handle = curl_init($url);\n\n    curl_setopt_array($handle, array(\n        CURLOPT_RETURNTRANSFER =&gt; true,\n        CURLOPT_CONNECTTIMEOUT =&gt; 3,\n        CURLOPT_TIMEOUT =&gt; 10,\n        CURLOPT_HTTPHEADER =&gt; array(\n            'Accept: application/json',\n            'X-Request-Id: ' . $requestId,\n        ),\n    ));\n\n    $body = curl_exec($handle);\n    $curlErrno = curl_errno($handle);\n    $curlError = curl_error($handle);\n    $info = curl_getinfo($handle);\n    curl_close($handle);\n\n    if ($body === false) {\n        throw new RuntimeException(json_encode(array(\n            'kind' =&gt; 'transport_error',\n            'request_id' =&gt; $requestId,\n            'curl_errno' =&gt; $curlErrno,\n            'curl_error' =&gt; $curlError,\n            'total_time' =&gt; $info['total_time'],\n        )));\n    }\n\n    $status = (int) $info['http_code'];\n    if ($status &lt; 200 || $status &gt;= 300) {\n        throw new RuntimeException(json_encode(array(\n            'kind' =&gt; 'http_error',\n            'request_id' =&gt; $requestId,\n            'http_code' =&gt; $status,\n            'content_type' =&gt; $info['content_type'],\n            'body_bytes' =&gt; strlen($body),\n        )));\n    }\n\n    return array(\n        'body' =&gt; $body,\n        'http_code' =&gt; $status,\n        'content_type' =&gt; $info['content_type'],\n        'total_time' =&gt; $info['total_time'],\n    );\n}</code></pre>\n<p>Снимайте сведения с handle до <code>curl_close()</code>. В диагностическую запись достаточно положить класс ошибки, request ID, статус, размер тела и время. URL нормализуйте: query-параметры могут содержать ключи, подписи и персональные данные. Тело не копируйте в общий журнал. Если расследование требует фрагмента, маскируйте его и ограничивайте отдельным безопасным контуром.</p>\n<h2>После 2xx проверьте контракт</h2>\n<p>Статус 2xx означает, что сервер принял запрос на протокольном уровне. Он не говорит, что ответ подходит вашему коду. Например, операция создания заказа может требовать объект с непустым <code>order_id</code>. Ответ <code>{&quot;accepted&quot;:true}</code> может быть валидным для другого endpoint, но не для этого.</p>\n<pre><code>&lt;?php\n\nfunction decodeCreatedOrder($body)\n{\n    $data = json_decode($body, true);\n\n    if (json_last_error() !== JSON_ERROR_NONE) {\n        throw new UnexpectedValueException('Response is not valid JSON');\n    }\n\n    if (!is_array($data)\n        || !isset($data['order_id'])\n        || !is_string($data['order_id'])\n        || $data['order_id'] === ''\n    ) {\n        throw new UnexpectedValueException('Response has no order_id');\n    }\n\n    return $data;\n}</code></pre>\n<p>Это тоже учебный пример. Он показывает порядок, а не готовую схему валидации для всех API. Для PHP 7.1 проверка <code>json_last_error()</code> нужна явно. В более новых версиях можно выбрать исключения декодера, но проверка типа ответа и обязательных полей всё равно остаётся.</p>\n<h2>Отрицательный путь: таймаут после записи</h2>\n<p>Таймаут опаснее явного 500. При 500 сервер сообщил об отказе. При таймауте клиент не знает, успел ли партнёр принять POST. Повтор может создать дубль заказа. Поэтому нельзя ставить одинаковое действие «повторить» на все ошибки.</p>\n<p>Повтор допустим только при понятном условии: операция идемпотентна, запрос содержит ключ идемпотентности или API позволяет запросить состояние по внешнему ID. Иначе сохраните неизвестный результат как отдельный класс. Человек или фоновая сверка должны выяснить судьбу первой попытки до новой записи.</p>\n<h2>Порядок внедрения и проверки</h2>\n<ol><li>Найдите проверки <code>if (!$body)</code> и замените их на строгое сравнение <code>$body === false</code>.</li><li>Соберите <code>curl_errno()</code>, <code>curl_error()</code> и <code>curl_getinfo()</code> сразу после вызова, пока handle открыт.</li><li>Разделите ошибки на <code>transport_error</code> и <code>http_error</code>; запишите request ID, статус и время без секретов.</li><li>Для каждого 2xx опишите ожидаемый тип тела и обязательные поля. Отдельно решите, допустим ли пустой ответ.</li><li>Проверьте учебный endpoint или с помощью mock-сервиса недоступный хост, 401, 404, 500, 200 с неверным JSON и 200 с неверной формой.</li><li>Добавьте сценарий таймаута после POST и убедитесь, что код не повторяет запись без ключа идемпотентности или проверки состояния.</li></ol>\n<h2>Ограничения</h2>\n<p>Эта схема не определяет, какие статусы считать повторяемыми. Решение зависит от метода, договора и побочных эффектов операции. Она также не решает проблему синтаксической ошибки в коде до запуска, не заменяет мониторинг веб-сервера и не доказывает доступность всех маршрутов партнёра.</p>\n<p>Не отключайте проверку TLS ради «успешного» запроса. Не записывайте Authorization, cookie и полный ответ в общий лог. Не называйте 2xx бизнес-успехом, пока код не проверил контракт. Эти ограничения важнее удобства короткой ветки <code>if ($body)</code>.</p>\n<h2>Проверяемый критерий готовности</h2>\n<p>Диагностика готова, если по каждой из шести проверок видно отдельное решение: транспортная ошибка, HTTP-отказ, неверный JSON, нарушение контракта, подтверждённый успех или неизвестный результат после таймаута. Для каждой записи доступны request ID и время, секреты не попадают в журнал, а повтор POST блокируется без доказанной идемпотентности. Это можно проверить локальным набором ответов, не выдавая учебные результаты за production-наблюдения.</p>\n<h2>Проверяемые источники</h2>\n<ul><li><a href=\"https://www.php.net/manual/en/function.curl-exec.php\" target=\"_blank\" rel=\"noopener\">PHP manual: curl_exec</a> — возвращаемое значение функции и отличие ошибки cURL от ответа HTTP</li><li><a href=\"https://www.php.net/manual/en/function.curl-getinfo.php\" target=\"_blank\" rel=\"noopener\">PHP manual: curl_getinfo</a> — сведения о последней передаче, включая HTTP-код и время</li><li><a href=\"https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes\" target=\"_blank\" rel=\"noopener\">RFC 9110, Status Codes</a> — официальная семантика кодов состояния HTTP</li></ul>"
}