PHP: полный мануал с примерами, функциями и ООП

Два файла: увидеть ответ другой программы

Нужно показать остаток товара, который хранится у другой программы. Сначала обе программы будут на вашем компьютере: одна принимает HTTP-запрос, другая его посылает. Получится строка Молоток — 8 шт. Здесь вы увидите реальную передачу, а не заранее записанный ответ внутри клиента.

Нужен PHP с расширением cURL. Команда php -m должна содержать curl; настройки CLI и PHP сайта могут различаться. Создайте отдельную папку и сохраните в ней два файла ниже в UTF-8. Начальные <?php включают PHP; круглые скобки содержат аргументы вызова, запятая отделяет их, точка с запятой завершает действие. Строка в кавычках — текст. В двойных кавычках означает перевод строки.

Файл server.php. header(...) сообщает получателю формат ответа; echo добавляет само содержимое. По умолчанию успешный ответ имеет статус 200. Сервер пока возвращает один заранее заданный товар.

<?php
header('Content-Type: text/plain; charset=UTF-8');
echo "Молоток — 8 шт.\n";

В первом терминале из этой папки выполните php -S 127.0.0.1:8791 server.php. Терминал остаётся занят сервером. Откройте второй терминал в той же папке: в нём затем выполните php example.php. Встроенный сервер подходит для этого локального опыта. Остановка — Ctrl+C в первом терминале. Адрес 127.0.0.1 означает эту машину, число после двоеточия — её порт.

<?php
declare(strict_types=1);

$base = getenv('PHP_MANUAL_LOCAL_URL') ?: 'http://127.0.0.1:8791';
$client = curl_init($base);
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($client);

Молоток — 8 шт.

Если порт занят, запустите сервер на 8792, а во втором PowerShell задайте $env:PHP_MANUAL_LOCAL_URL = 'http://127.0.0.1:8792'. Оба процесса должны использовать один порт. Клиент запускается в CLI: обращение обработчика обратно к тому же занятому однопоточному серверу может заблокировать опыт.

От короткого вызова к проверке отказов

Теперь нужен пригодный для работы клиент: если сервер выключен, человек должен получить понятное сообщение; если сервер сообщил HTTP 404, это отдельный исход. if выполняет блок в фигурных скобках при истинном условии. === false проверяет именно логический отказ: строка "0" — полноценное тело, а пустая строка может быть нормальным ответом 204. throw прерывает работу исключением; на границе приложения его перехватывает catch.

<?php
declare(strict_types=1);

require __DIR__ . '/base.php';
$client = curl_init($base . '/product?id=1');
if ($client === false) { throw new RuntimeException('cURL не создал клиент'); }
curl_setopt_array($client, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 2, CURLOPT_CONNECTTIMEOUT => 1]);
$body = curl_exec($client);
if ($body === false) { throw new RuntimeException('Нет ответа: '.curl_error($client)); }
if (curl_getinfo($client, CURLINFO_RESPONSE_CODE) !== 200) { throw new RuntimeException('Сервис отклонил запрос'); }
echo $body;

Молоток — 8 шт.

В следующих архивах require __DIR__ . '/base.php' подключает общий файл настроек рядом с примером. __DIR__ — каталог самого файла, точка соединяет строки. Полный файл ниже: ?? подставляет значение при отсутствующем ключе, || означает «или», isset проверяет наличие, !== — строгое несовпадение. Проверка допускает только собственный HTTP-стенд, поэтому адрес не берётся из посетительской формы.

<?php
$base = getenv('PHP_MANUAL_LOCAL_URL') ?: 'http://127.0.0.1:8791';
$parts = parse_url($base);
if ($parts === false || ($parts['scheme'] ?? '') !== 'http'
    || ($parts['host'] ?? '') !== '127.0.0.1'
    || isset($parts['user']) || isset($parts['pass']) || isset($parts['query'])
    || isset($parts['fragment']) || !empty($parts['path'])) {
    throw new RuntimeException('Учебный сервер должен находиться на http://127.0.0.1:порт');
}

Какие заголовки и байты получает сервер

Одинаковые PHP-массивы можно передать разными форматами. Сервер разбирает байты тела и Content-Type. Передача массива в POSTFIELDS создаёт multipart; передача готовой строки формы даёт urlencoded; JSON требует json_encode и явного заголовка. Следующие опыты вызывают один собственный /inspect: он возвращает то, что действительно получил.

http_build_query кодирует пары полей для формы. Ключ quantity становится именем поля; число 2 превращается в текст 2. json_encode сохраняет JSON-число; у JSON нет автоматического заполнения $_POST. json_decode(..., true) превращает полученный объект JSON в ассоциативный массив PHP, где значение читают как $reply['raw'].

<?php
declare(strict_types=1);

require __DIR__ . '/base.php';
$client = curl_init($base . '/inspect');
curl_setopt_array($client, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 2, CURLOPT_CONNECTTIMEOUT => 1]);
curl_setopt_array($client, [CURLOPT_POST=>true, CURLOPT_POSTFIELDS=>http_build_query(['sku'=>'A42', 'quantity'=>2]), CURLOPT_HTTPHEADER=>['Content-Type: application/x-www-form-urlencoded']]);
$body = curl_exec($client);
if ($body === false) { throw new RuntimeException('Нет ответа: '.curl_error($client)); }
if (curl_getinfo($client, CURLINFO_RESPONSE_CODE) !== 200) { throw new RuntimeException('Сервис отклонил запрос'); }
$reply = json_decode($body, true, 8, JSON_THROW_ON_ERROR);
echo $reply['method'], "\n", explode(';', $reply['content_type'])[0], "\n";
echo 'Тело: ', $reply['raw'], "\n";
echo 'Поля формы: ', json_encode($reply['fields'], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR), "\n";

POST
application/x-www-form-urlencoded
Тело: sku=A42&quantity=2
Поля формы: {"sku":"A42","quantity":"2"}

<?php
declare(strict_types=1);

require __DIR__ . '/base.php';
$client = curl_init($base . '/inspect');
curl_setopt_array($client, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 2, CURLOPT_CONNECTTIMEOUT => 1]);
curl_setopt_array($client, [CURLOPT_POST=>true, CURLOPT_POSTFIELDS=>json_encode(['sku'=>'A42', 'quantity'=>2], JSON_THROW_ON_ERROR), CURLOPT_HTTPHEADER=>['Content-Type: application/json']]);
$body = curl_exec($client);
if ($body === false) { throw new RuntimeException('Нет ответа: '.curl_error($client)); }
if (curl_getinfo($client, CURLINFO_RESPONSE_CODE) !== 200) { throw new RuntimeException('Сервис отклонил запрос'); }
$reply = json_decode($body, true, 8, JSON_THROW_ON_ERROR);
echo $reply['method'], "\n", explode(';', $reply['content_type'])[0], "\n";
echo 'Тело: ', $reply['raw'], "\n";
echo 'Поля формы: ', json_encode($reply['fields'], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR), "\n";

POST
application/json
Тело: {"sku":"A42","quantity":2}
Поля формы: []

<?php
declare(strict_types=1);

require __DIR__ . '/base.php';
$client = curl_init($base . '/inspect');
curl_setopt_array($client, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 2, CURLOPT_CONNECTTIMEOUT => 1]);
curl_setopt_array($client, [CURLOPT_POST=>true, CURLOPT_POSTFIELDS=>['sku'=>'A42', 'quantity'=>'2'], CURLOPT_HTTPHEADER=>[]]);
$body = curl_exec($client);
if ($body === false) { throw new RuntimeException('Нет ответа: '.curl_error($client)); }
if (curl_getinfo($client, CURLINFO_RESPONSE_CODE) !== 200) { throw new RuntimeException('Сервис отклонил запрос'); }
$reply = json_decode($body, true, 8, JSON_THROW_ON_ERROR);
echo $reply['method'], "\n", explode(';', $reply['content_type'])[0], "\n";
echo 'Поля формы: ', json_encode($reply['fields'], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR), "\n";

POST
multipart/form-data
Поля формы: {"sku":"A42","quantity":"2"}

При стандартной обработке multipart PHP расходует тело на поля и файлы; отсутствие его копии в php://input не означает, что данные не пришли. Файлы попадают в $_FILES. Передача настоящего inventory.txt показывает отдельный полный опыт. Чтобы увидеть реализацию /inspect, откройте следующий исходник стенда.

Живой расчёт цены: запрос, проверка и ответ

Следующая задача полезна человеку: запросить цену двух молотков. Клиент посылает только id=1 и quantity=2. Цена 450 и остаток 8 принадлежат серверному каталогу; посетитель не должен назначать их своей строкой запроса. Результат: Молоток: 2 шт.; 900 руб. Это предложение цены, без оплаты и списания склада.

server.php этого опыта. Это самостоятельный небольшой обработчик. Скопируйте его из архива и запустите той же командой сервера, предварительно остановив предыдущий. Проверка media type намеренно строгая для точно показанного клиента; общий обработчик может отдельно разбирать допустимые параметры Content-Type.

<?php
header('Content-Type: application/json; charset=UTF-8');
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    header('Allow: POST');
    echo '{"error":"Нужен POST"}';
    exit;
}
if (($_SERVER['CONTENT_TYPE'] ?? '') !== 'application/json') {
    http_response_code(415);
    echo '{"error":"Нужен application/json"}';
    exit;
}
$raw = file_get_contents('php://input', false, null, 0, 4097);
try {
    if ($raw === false || strlen($raw) > 4096) {
        throw new RuntimeException('Слишком большое тело');
    }
    $input = json_decode($raw, true, 8, JSON_THROW_ON_ERROR);
    if (!is_array($input) || ($input['id'] ?? null) !== 1
        || !is_int($input['quantity'] ?? null) || $input['quantity'] < 1) {
        throw new RuntimeException('Нужны id=1 и целое quantity от 1');
    }
} catch (JsonException | RuntimeException $error) {
    http_response_code(400);
    echo '{"error":"Проверьте id и целое количество"}';
    exit;
}
if ($input['quantity'] > 8) {
    http_response_code(409);
    echo '{"error":"На складе только 8 штук"}';
    exit;
}
$reply = ['product'=>'Молоток', 'quantity'=>$input['quantity'],
    'unit_price'=>450, 'total'=>450 * $input['quantity']];
echo json_encode($reply, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);

example.php. Настройки заголовков — массив полных строк; Accept описывает желаемый формат ответа, Content-Type — формат отправленного тела. Сначала проверяется транспорт, затем HTTP-статус, формат и поля. Текст ошибки оператора не следует выводить посетителю вместо понятного сообщения.

<?php
declare(strict_types=1);

require __DIR__ . '/base.php';
$request = json_encode(['id'=>1, 'quantity'=>2], JSON_THROW_ON_ERROR);
$client = curl_init($base . '/quote');
curl_setopt_array($client, [
    CURLOPT_RETURNTRANSFER=>true, CURLOPT_TIMEOUT=>2,
    CURLOPT_CONNECTTIMEOUT=>1, CURLOPT_POST=>true,
    CURLOPT_HTTPHEADER=>['Content-Type: application/json', 'Accept: application/json'],
    CURLOPT_POSTFIELDS=>$request,
]);
$body = curl_exec($client);
if ($body === false) { throw new RuntimeException('Сервис не ответил: '.curl_error($client)); }
$status = curl_getinfo($client, CURLINFO_RESPONSE_CODE);
$type = curl_getinfo($client, CURLINFO_CONTENT_TYPE);
if ($type === null || !str_starts_with(strtolower($type), 'application/json')) {
    throw new RuntimeException('Сервис вернул другой формат');
}
$reply = json_decode($body, true, 8, JSON_THROW_ON_ERROR);
if ($status !== 200) {
    echo 'Предложение не создано: ', $reply['error'] ?? 'неизвестная причина', "\n";
} else {
    if (!is_array($reply) || !is_string($reply['product'] ?? null)
        || !is_int($reply['quantity'] ?? null) || !is_int($reply['total'] ?? null)) {
        throw new RuntimeException('В ответе нет нужных полей');
    }
    echo $reply['product'], ': ', $reply['quantity'], ' шт.; ', $reply['total'], " руб.\n";
}

Молоток: 2 шт.; 900 руб.

<?php
declare(strict_types=1);

require __DIR__ . '/base.php';
$request = json_encode(['id'=>1, 'quantity'=>9], JSON_THROW_ON_ERROR);
$client = curl_init($base . '/quote');
curl_setopt_array($client, [
    CURLOPT_RETURNTRANSFER=>true, CURLOPT_TIMEOUT=>2,
    CURLOPT_CONNECTTIMEOUT=>1, CURLOPT_POST=>true,
    CURLOPT_HTTPHEADER=>['Content-Type: application/json', 'Accept: application/json'],
    CURLOPT_POSTFIELDS=>$request,
]);
$body = curl_exec($client);
if ($body === false) { throw new RuntimeException('Сервис не ответил: '.curl_error($client)); }
$status = curl_getinfo($client, CURLINFO_RESPONSE_CODE);
$type = curl_getinfo($client, CURLINFO_CONTENT_TYPE);
if ($type === null || !str_starts_with(strtolower($type), 'application/json')) {
    throw new RuntimeException('Сервис вернул другой формат');
}
$reply = json_decode($body, true, 8, JSON_THROW_ON_ERROR);
if ($status !== 200) {
    echo 'Предложение не создано: ', $reply['error'] ?? 'неизвестная причина', "\n";
} else {
    if (!is_array($reply) || !is_string($reply['product'] ?? null)
        || !is_int($reply['quantity'] ?? null) || !is_int($reply['total'] ?? null)) {
        throw new RuntimeException('В ответе нет нужных полей');
    }
    echo $reply['product'], ': ', $reply['quantity'], ' шт.; ', $reply['total'], " руб.\n";
}

Предложение не создано: На складе только 8 штук

<?php
declare(strict_types=1);

require __DIR__ . '/base.php';
$request = json_encode(['id'=>1, 'quantity'=>'2'], JSON_THROW_ON_ERROR);
$client = curl_init($base . '/quote');
curl_setopt_array($client, [
    CURLOPT_RETURNTRANSFER=>true, CURLOPT_TIMEOUT=>2,
    CURLOPT_CONNECTTIMEOUT=>1, CURLOPT_POST=>true,
    CURLOPT_HTTPHEADER=>['Content-Type: application/json', 'Accept: application/json'],
    CURLOPT_POSTFIELDS=>$request,
]);
$body = curl_exec($client);
if ($body === false) { throw new RuntimeException('Сервис не ответил: '.curl_error($client)); }
$status = curl_getinfo($client, CURLINFO_RESPONSE_CODE);
$type = curl_getinfo($client, CURLINFO_CONTENT_TYPE);
if ($type === null || !str_starts_with(strtolower($type), 'application/json')) {
    throw new RuntimeException('Сервис вернул другой формат');
}
$reply = json_decode($body, true, 8, JSON_THROW_ON_ERROR);
if ($status !== 200) {
    echo 'Предложение не создано: ', $reply['error'] ?? 'неизвестная причина', "\n";
} else {
    if (!is_array($reply) || !is_string($reply['product'] ?? null)
        || !is_int($reply['quantity'] ?? null) || !is_int($reply['total'] ?? null)) {
        throw new RuntimeException('В ответе нет нужных полей');
    }
    echo $reply['product'], ': ', $reply['quantity'], ' шт.; ', $reply['total'], " руб.\n";
}

Предложение не создано: Проверьте id и целое количество

Упражнение: запросите три молотка. Предложенный ответ — Молоток: 3 шт.; 1350 руб.. Затем замените quantity на массив: ожидается 400 и сообщение о проверке количества. Не меняйте цену в клиенте: в этом договоре её там вообще нет. Для повторов изменяющих операций сначала нужен договор идемпотентности; повтор расчёта и повтор оплаты — разные действия.

Ноль, пустой ответ, HTTP-ошибка и сломанный JSON

Сеть может успешно вернуть ноль, пустое тело, HTTP-ошибку или испорченный JSON. Для каждого случая нужна своя политика. В следующем опыте стенд намеренно даёт все эти ответы, а клиент сообщает результат по смыслу.

foreach повторяет тело блока для каждого пути; elseif выбирает следующий случай только если предыдущий не подошёл. Внутри цикла новый клиент отделяет настройки одного опыта от другого. Это четыре заданных ответа своего сервера, поэтому их смысл известен заранее.

<?php
declare(strict_types=1);

require __DIR__ . '/base.php';
foreach (['/zero', '/empty', '/json/product?id=99', '/broken-json'] as $path) {
    $client = curl_init($base . $path);
    curl_setopt_array($client, [CURLOPT_RETURNTRANSFER=>true, CURLOPT_TIMEOUT=>2]);
    $body = curl_exec($client);
    if ($body === false) { throw new RuntimeException(curl_error($client)); }
    $status = curl_getinfo($client, CURLINFO_RESPONSE_CODE);
    if ($status === 204) { echo "204: ответ без тела\n"; }
    elseif ($status === 404) { echo "404: товар не найден\n"; }
    elseif ($path === '/zero') { echo '200: текст ', $body, "\n"; }
    else {
        try { json_decode($body, true, 8, JSON_THROW_ON_ERROR); }
        catch (JsonException $error) { echo "200: неверный JSON, товар не показываем\n"; }
    }
}

200: текст 0
204: ответ без тела
404: товар не найден
200: неверный JSON, товар не показываем

Полный локальный сервер для справочных карточек

Все предыдущие карточки, кроме двух явно уменьшенных серверов, используют этот стенд. Его исходник находится в каждом архиве. Здесь функции появляются после простого обработчика: reply собирает единый JSON-ответ и завершает запрос. Условия по пути выбирают маршрут, таблица $catalog задаёт весь набор данных. Для POST /quote проверены метод, Content-Type, размер, JSON и типы. /upload только читает временный учебный файл, не публикует его.

<?php
declare(strict_types=1);
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$method = $_SERVER['REQUEST_METHOD'];
$products = [
    1 => ['id'=>1, 'name'=>'Молоток', 'stock'=>8, 'price'=>450],
    2 => ['id'=>2, 'name'=>'Перчатки', 'stock'=>15, 'price'=>120],
    3 => ['id'=>3, 'name'=>'Кисть', 'stock'=>0, 'price'=>80],
];
function reply(int $status, array $data): never {
    http_response_code($status);
    header('Content-Type: application/json; charset=UTF-8');
    header('Cache-Control: no-store');
    echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
    exit;
}
if ($path === '/health') { header('Content-Type: text/plain'); exit('ready'); }
if ($path === '/empty') { http_response_code(204); exit; }
if ($path === '/zero') { header('Content-Type: text/plain'); exit('0'); }
if ($path === '/broken-json') { header('Content-Type: application/json'); exit('{broken'); }
if ($path === '/redirect') { header('Location: /product?id=1', true, 302); exit; }
if ($path === '/product' || $path === '/json/product') {
    $rawId = $_GET['id'] ?? null;
    if (!is_string($rawId) || !ctype_digit($rawId)) { reply(400, ['error'=>'Нужен целый номер товара']); }
    $product = $products[(int)$rawId] ?? null;
    if ($product === null) { reply(404, ['error'=>'Товар не найден']); }
    header('X-Catalog: workshop');
    if ($path === '/json/product') { reply(200, $product); }
    header('Content-Type: text/plain; charset=UTF-8');
    echo $product['name'], ' — ', $product['stock'], " шт.\n";
    exit;
}
if ($path === '/quote') {
    if ($method !== 'POST') { header('Allow: POST'); reply(405, ['error'=>'Нужен POST']); }
    $type = strtolower(trim(explode(';', $_SERVER['CONTENT_TYPE'] ?? '')[0]));
    if ($type !== 'application/json') { reply(415, ['error'=>'Нужен Content-Type application/json']); }
    $raw = file_get_contents('php://input', false, null, 0, 4097);
    if ($raw === false || strlen($raw) > 4096) { reply(413, ['error'=>'Тело запроса слишком велико']); }
    try { $input = json_decode($raw, true, 8, JSON_THROW_ON_ERROR); }
    catch (JsonException) { reply(400, ['error'=>'Повреждён JSON']); }
    if (!is_array($input) || !is_int($input['id'] ?? null) || !is_int($input['quantity'] ?? null)
        || $input['quantity'] < 1 || $input['quantity'] > 100) { reply(422, ['error'=>'Нужны целые id и quantity от1 до100']); }
    $product = $products[$input['id']] ?? null;
    if ($product === null) { reply(404, ['error'=>'Товар не найден']); }
    if ($input['quantity'] > $product['stock']) { reply(409, ['error'=>'Недостаточно товара']); }
    reply(200, ['product'=>$product['name'], 'quantity'=>$input['quantity'],
        'unit_price'=>$product['price'], 'total'=>$product['price']*$input['quantity']]);
}
if ($path === '/inspect') {
    $type = $_SERVER['CONTENT_TYPE'] ?? '';
    $raw = file_get_contents('php://input');
    reply(200, ['method'=>$method, 'content_type'=>$type,
        'request_id'=>$_SERVER['HTTP_X_REQUEST_ID'] ?? null, 'raw'=>$raw, 'fields'=>$_POST, 'query'=>$_GET]);
}
if ($path === '/upload') {
    if ($method !== 'POST') { header('Allow: POST'); reply(405, ['error'=>'Нужен POST']); }
    $file = $_FILES['inventory'] ?? null;
    if (!is_array($file) || ($file['error'] ?? null) !== UPLOAD_ERR_OK
        || !is_string($file['tmp_name'] ?? null) || !is_uploaded_file($file['tmp_name'])) {
        reply(422, ['error'=>'Ожидается файл inventory']);
    }
    if ($file['size'] > 4096) { reply(413, ['error'=>'Файл слишком велик']); }
    $data = file_get_contents($file['tmp_name']);
    if ($data === false) { reply(500, ['error'=>'Временный файл не читается']); }
    reply(200, ['name'=>$file['name'], 'declared_type'=>$file['type'], 'data'=>$data]);
}
if ($path === '/cookie/set' || $path === '/cookie/raw') {
    $before = $_COOKIE['theme'] ?? 'не выбрана';
    $options = ['path'=>'/', 'httponly'=>true, 'samesite'=>'Lax'];
    if ($path === '/cookie/raw') { setrawcookie('theme', 'blue%20sky', $options); }
    else { setcookie('theme', 'blue sky', $options); }
    header('Content-Type: text/plain; charset=UTF-8');
    echo 'Тема входящего запроса: ', $before, "\n";
    exit;
}
if ($path === '/cookie/read') {
    header('Content-Type: text/plain; charset=UTF-8');
    echo 'Тема следующего запроса: ', $_COOKIE['theme'] ?? 'не выбрана', "\n";
    exit;
}
if ($path === '/headers/list') {
    header('Content-Type: text/plain; charset=UTF-8');
    header('X-Catalog: workshop');
    $selected = array_values(array_filter(headers_list(), fn($line) => str_starts_with($line, 'X-Catalog:')));
    echo implode("\n", $selected), "\nМолоток — 8 шт.\n";
    exit;
}
if ($path === '/headers/remove') {
    header('X-Debug-Token: temporary');
    header_remove('X-Debug-Token');
    header('X-Catalog: workshop');
    header('Content-Type: text/plain; charset=UTF-8');
    exit("Молоток — 8 шт.\n");
}
if ($path === '/headers/callback') {
    header_register_callback(function (): void { header('X-Report-State: prepared'); });
    header('Content-Type: text/plain; charset=UTF-8');
    exit("Молоток — 8 шт.\n");
}
if ($path === '/headers/sent') {
    ob_start();
    echo "Молоток — 8 шт.\n";
    if (headers_sent($file, $line)) { throw new RuntimeException('Ответ уже отправлен'); }
    header('Content-Type: text/plain; charset=UTF-8');
    header('X-Report-State: prepared-before-output');
    ob_end_flush();
    exit;
}
if ($path === '/parse-body') {
    if ($method !== 'PUT') { header('Allow: PUT'); reply(405, ['error'=>'Нужен PUT']); }
    [$fields, $files] = request_parse_body();
    reply(200, ['fields'=>$fields, 'files'=>array_keys($files)]);
}
reply(404, ['error'=>'Маршрут не найден']);

Переход к HTTPS на настоящем сервисе требует доверенной цепочки сертификатов и проверки имени. Локальный HTTP-опыт не проверяет TLS. Нельзя переносить учебную привязку loopback, отсутствие авторизации и development server как готовую публичную инфраструктуру. Установка CA и проверка HTTPS.

Что значит вызвать API другого сервиса

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

Что уже пригодится. переменная и присваивание, массив, объявление и вызов функции, JSON и вложенные данные

Вызов HTTP и разбор JSON — разные действия. Можно получить ответ 500, HTML вместо JSON или корректный JSON неподходящей формы. В самом маленьком опыте сначала изучим только последнюю часть без сети.

Этот вариант. Это сохранённый учебный ответ, а не обращение к реальному перевозчику. true просит представить JSON-объект как PHP-массив; флаг JSON_THROW_ON_ERROR превращает ошибку разбора в исключение. Эти параметры разобраны в главе JSON. Копейки не переводим в float для вычислений.

<?php
declare(strict_types=1);

$body = '{"delivery_kopecks":29900}';
$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!is_array($data) || !isset($data['delivery_kopecks']) || !is_int($data['delivery_kopecks'])) {
    throw new UnexpectedValueException('Ответ не соответствует договору');
}
echo $data['delivery_kopecks'], "\n";

29900

Следующая ступень. Теперь связываем тот же разбор с HTTP-клиентом, таймаутом, авторизацией и проверкой статуса. Ниже приведены вызовы cURL и причины выбора библиотеки.

Успешное соединение ещё не означает успешную операцию

Сервис доставки присылает тарифы в JSON. Для получения результата приложение должно пройти несколько границ: разрешить адрес, установить соединение, проверить TLS, дождаться HTTP-ответа, оценить статус, разобрать JSON и проверить ожидаемую структуру. На каждом этапе возможна самостоятельная ошибка. curl_exec может успешно вернуть HTML страницы 404: транспорт сработал, но бизнес-результата нет.

Не сводите эти ошибки к одному пустому массиву. Таймаут может требовать отложенного повтора, 401 — исправления учётных данных, 422 — изменения запроса, 429 — ожидания по политике сервиса. Ответ 200 с некорректным JSON — нарушение протокола. Валидный JSON null тоже не является списком тарифов. Проверяйте обязательные ключи, типы и диапазоны после json_decode.

URL интеграции лучше задавать конфигурацией, а пользователь передаёт только ограниченный идентификатор. Если сервер скачивает произвольный URL, возникает SSRF: можно обратиться к локальным сервисам или облачным метаданным. Проверка строки через FILTER_VALIDATE_URL не решает эту задачу. Для произвольных адресов нужны политика DNS/IP, запрет внутренних диапазонов, контроль перенаправлений и сетевые ограничения. Фиксированный доверенный endpoint сильно упрощает задачу.

Ограничиваем время и размер ответа

Этот вариант. Нужны cURL, доверенный endpoint и актуальные CA. Это определение функции, без сетевого вызова; проверен синтаксис. example.com обозначает место вашего контрактного API. Каждую запись rates затем проверяют отдельно. Не выключайте проверку сертификата для устранения ошибки окружения.

<?php
declare(strict_types=1);

function fetchRates(string $postcode): array {
    if (!preg_match('/\A[0-9]{6}\z/D',$postcode)) throw new InvalidArgumentException('postcode');
    $url = 'https://api.example.com/rates?'.http_build_query(['postcode'=>$postcode]);
    $curl = curl_init($url);
    if ($curl === false) throw new RuntimeException('Cannot create HTTP client');
    $body = '';
    $tooLarge = false;
    curl_setopt_array($curl,[
        CURLOPT_CONNECTTIMEOUT_MS=>1500, CURLOPT_TIMEOUT_MS=>5000,
        CURLOPT_FOLLOWLOCATION=>false,
        CURLOPT_PROTOCOLS=>CURLPROTO_HTTPS,
        CURLOPT_SSL_VERIFYPEER=>true, CURLOPT_SSL_VERIFYHOST=>2,
        CURLOPT_HTTPHEADER=>['Accept: application/json'],
        CURLOPT_WRITEFUNCTION=>static function ($handle,string $chunk) use (&$body,&$tooLarge): int {
            if (strlen($body)+strlen($chunk)>1_000_000) { $tooLarge=true; return 0; }
            $body .= $chunk;
            return strlen($chunk);
        },
    ]);
    $ok = curl_exec($curl);
    $status = curl_getinfo($curl,CURLINFO_RESPONSE_CODE);
    if ($tooLarge) throw new RuntimeException('Response too large');
    if ($ok === false) throw new RuntimeException('Transport failure: '.curl_errno($curl));
    if ($status !== 200) throw new RuntimeException('Unexpected HTTP status: '.$status);
    $data = json_decode($body,true,64,JSON_THROW_ON_ERROR);
    if (!is_array($data) || !isset($data['rates']) || !is_array($data['rates'])) {
        throw new UnexpectedValueException('Invalid API schema');
    }
    return $data['rates'];
}

Лимит времени соединения и общий таймаут отвечают на разные вопросы. Без общего таймаута сервер может очень медленно отправлять тело. Ограничение Content-Length недостаточно: заголовок может отсутствовать или быть недостоверным. Callback ограничивает реально накопленные байты. Если включена распаковка, учитывайте размер уже распакованного результата. Не выводите curl_error с внутренним адресом пользователю.

Редиректы запрещены в примере намеренно: новый адрес требует отдельного решения о доверии, особенно если отправляется Authorization. Для изменяющих запросов не включайте автоматические повторы без знания семантики сервиса. При HTTPS-проблеме настройте CA и проверьте часы сервера, а не отключайте CURLOPT_SSL_VERIFYPEER.

Разбор JSON и проверка прикладного контракта

Этот вариант. Пример отличает повреждённый JSON от нарушения схемы. Денежное значение ожидается целым числом минимальных единиц, поэтому строка отвергается. Если API документирует decimal-строку, нужен другой валидатор, а не случайное приведение float.

<?php
declare(strict_types=1);

function readRate(string $body): int {
    $value = json_decode($body,true,16,JSON_THROW_ON_ERROR);
    if (!is_array($value) || !is_int($value['priceMinor'] ?? null)
        || $value['priceMinor'] < 0 || ($value['currency'] ?? null) !== 'RUB') {
        throw new UnexpectedValueException('rate-schema');
    }
    return $value['priceMinor'];
}
foreach (['{"priceMinor":39000,"currency":"RUB"}',
    '{"priceMinor":"39000","currency":"RUB"}', '{oops'] as $body) {
    try { echo readRate($body)."
"; }
    catch (JsonException) { echo "invalid-json
"; }
    catch (UnexpectedValueException) { echo "invalid-schema
"; }
}

39000
invalid-schema
invalid-json

Секреты, наблюдаемость и тестирование

Храните credentials отдельно от URL, чтобы они не попали в журналы прокси и историю. Заголовки Authorization и подписи редактируют перед логированием. Для диагностики сохраняйте код статуса, длительность, идентификатор запроса провайдера, номер попытки и безопасный код ошибки. Полное тело ответа может содержать персональные данные и не должно попадать в общий лог автоматически.

Клиентскую библиотеку удобно скрыть за интерфейсом. В тестах подставляйте ответы 200, 401, 429, 503, повреждённый JSON и обрыв соединения. Отдельный контрактный тест работает с sandbox сервиса. Успех локального JSON-теста не означает, что боевые сертификаты, прокси и права настроены. Схема может изменяться: неизвестные необязательные поля обычно можно игнорировать, но исчезновение обязательного поля следует обнаружить сразу.

Для каталога допустим короткий кеш и последняя успешная цена с пометкой времени; для списания денег такое поведение неприемлемо. Политику деградации выбирают по задаче. Когда внешний сервис долго недоступен, ограничение параллельности и временное прекращение попыток защищают ваше приложение от исчерпания воркеров. Эти решения полезнее бесконечного увеличения таймаута.

Массивы из API и устойчивость контракта

Внешний JSON часто содержит массив заказов, внутри каждого — массив позиций, а внутри позиции — вложенный объект цены. После json_decode(..., true) это становится многомерным PHP-массивом. Однако ключ items ещё не доказывает список: проверьте is_array и при необходимости array_is_list, затем каждую запись. Отдельно ограничьте число заказов и позиций, чтобы формально корректное тело не запустило чрезмерную работу.

Не все числовые строки являются числами для вычислений. Артикул 00042, телефон и внешний ID могут требовать сохранения ведущих нулей. Очень большой JSON integer способен не помещаться в PHP int; JSON_BIGINT_AS_STRING помогает сохранить цифры, если контракт допускает такой идентификатор. Денежные decimal-значения требуют точной стратегии, а не безусловного float. Ошибка схемы должна указывать безопасный путь вроде orders[3].items[2].quantity, чтобы интеграцию можно было исправить.

Клиент может исчезнуть во время ожидания, но это не отменяет уже выполненную операцию партнёра. Сохраняйте внешний correlation/idempotency ID до вызова, если он определяет восстановление. Общий бюджет запроса распределяют между попытками, DNS, соединением и чтением. Три попытки по пять секунд плюс паузы не укладываются в HTTP-дедлайн десять секунд; политика должна учитывать весь путь.

Практика: проверьте решение, а не только успешный путь

API вернул 200 и {"rates":null}; curl_exec не вернул false. Можно ли считать тарифы пустыми?