🐘 PHP

PHP中的网络与HTTP API操作：详细指南

课程 33 / 35 • 完整阅读理论

Что это такое и зачем? (аналогия из реальной жизни)

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

HTTP API (Application Programming Interface) — это тот самый «официант», который передаёт вашу просьбу (запрос) на удалённый сервер (кухню) и приносит ответ (пиццу). Ваша программа на PHP — это клиент, который делает заказ. Сервер — это мощный компьютер, который хранит данные или выполняет сложные вычисления.

Зачем это нужно? Представьте, что вы пишете сайт погоды. Вы же не будете сами устанавливать метеостанции по всему миру? Вместо этого вы обращаетесь к API сервиса погоды (например, OpenWeatherMap), отправляете запрос: «Какая погода в Москве?», и получаете готовый ответ с температурой, влажностью и ветром. Ваш сайт просто показывает эти данные пользователю.

Другой пример: вы хотите, чтобы пользователи могли входить на ваш сайт через свой аккаунт ВКонтакте или Google. Вместо того чтобы создавать свою систему регистрации, вы используете API этих соцсетей. Ваш сайт отправляет запрос: «Этот пользователь действительно тот, за кого себя выдаёт?», и получает подтверждение.

💡 Важно: HTTP API — это не просто «скачать файл из интернета». Это полноценный протокол общения между программами, где есть правила, форматы данных и коды ответов.

В современной веб-разработке без работы с API не обходится ни один серьёзный проект: от интернет-магазинов (оплата через банк) до социальных сетей (загрузка фото) и мессенджеров (отправка сообщений).

Теория: как это работает изнутри

Чтобы понять, как работает HTTP API, нужно разобраться с самим протоколом HTTP (HyperText Transfer Protocol). Это язык, на котором общаются все программы в интернете.

Основные понятия

Клиент — это программа, которая отправляет запрос. В нашем случае это PHP-скрипт, который работает на вашем сервере или локальном компьютере.

Сервер — это программа на удалённом компьютере, которая принимает запросы, обрабатывает их и отправляет ответ.

Запрос (Request) состоит из нескольких частей:

Метод — действие, которое мы хотим выполнить (GET, POST, PUT, DELETE и другие)
URL — адрес ресурса, к которому обращаемся (например, https://api.weather.com/v1/forecast)
Заголовки (Headers) — дополнительная информация (тип данных, авторизация, язык)
Тело (Body) — данные, которые мы отправляем (обычно в формате JSON)

Ответ (Response) состоит из:

Код статуса — трёхзначное число, которое говорит, как прошёл запрос (200 — успешно, 404 — не найдено, 500 — ошибка сервера)
Заголовки — служебная информация от сервера
Тело — сами данные (обычно JSON или XML)

Методы HTTP

Метод	Что делает	Аналогия в жизни
GET	Получает данные	Посмотреть меню ресторана
POST	Создаёт новый ресурс	Сделать заказ
PUT	Обновляет существующий ресурс	Изменить заказ (заменить блюдо)
PATCH	Частично обновляет ресурс	Попросить добавить сыр в уже готовую пиццу
DELETE	Удаляет ресурс	Отменить заказ

Коды статуса HTTP

Код	Категория	Примеры
1xx	Информационные	101 — переключение протокола
2xx	Успех	200 OK, 201 Created, 204 No Content
3xx	Перенаправление	301 Moved Permanently, 302 Found
4xx	Ошибка клиента	400 Bad Request, 401 Unauthorized, 404 Not Found
5xx	Ошибка сервера	500 Internal Server Error, 503 Service Unavailable

Форматы данных

Самый популярный формат для обмена данными в API — JSON (JavaScript Object Notation). Он выглядит как обычный текст, но строго структурирован:

{
  "city": "Москва",
  "temperature": 22.5,
  "humidity": 65,
  "wind": {
    "speed": 3.2,
    "direction": "северо-западный"
  }
}

Раньше часто использовали XML, но сейчас JSON — стандарт де-факто. PHP отлично работает с JSON через функции json_encode() и json_decode().

Синтаксис в PHP: все формы и варианты

В PHP есть несколько способов отправлять HTTP-запросы. Мы рассмотрим три основных подхода: от самого простого до самого гибкого.

1. Функция file_get_contents()

Самый простой способ — использовать встроенную функцию file_get_contents(). Она умеет читать не только локальные файлы, но и удалённые URL.

<?php
// Простейший GET-запрос
$response = file_get_contents('https://api.example.com/data');
echo $response;
?>

Но у этого способа есть недостатки: сложно отправлять POST-запросы, нельзя управлять заголовками, нет обработки ошибок.

2. Расширение cURL

cURL (Client URL) — это мощное расширение PHP для работы с сетью. Оно поддерживает все методы HTTP, заголовки, таймауты, сертификаты и многое другое.

<?php
// Инициализация сессии cURL
$ch = curl_init();

// Установка URL
curl_setopt($ch, CURLOPT_URL, 'https://api.example.com/data');

// Возвращать результат в виде строки, а не выводить сразу
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Выполнение запроса
$response = curl_exec($ch);

// Проверка на ошибки
if (curl_errno($ch)) {
    echo 'Ошибка cURL: ' . curl_error($ch);
}

// Закрытие сессии
curl_close($ch);
?>

3. Guzzle HTTP Client

Guzzle — это сторонняя библиотека (composer-пакет), которая делает работу с HTTP ещё удобнее. Она предоставляет объектно-ориентированный интерфейс и множество готовых решений.

<?php
require 'vendor/autoload.php';

use GuzzleHttpClient;

$client = new Client();
$response = $client->get('https://api.example.com/data');
$body = $response->getBody()->getContents();
?>

Сравнение методов

Метод	Сложность	Гибкость	Когда использовать
file_get_contents()	Очень низкая	Низкая	Простые GET-запросы, прототипы
cURL	Средняя	Высокая	Серьёзные проекты, нужен полный контроль
Guzzle	Средняя (но удобный API)	Очень высокая	Современные проекты, работа с API

Примеры кода — от простого к сложному

Пример 1: Простой GET-запрос с file_get_contents()

<?php
/**
 * Пример 1: Получение списка пользователей с тестового API
 * Используем самый простой способ — file_get_contents()
 */

// URL тестового API (JSONPlaceholder — бесплатный сервис для тестирования)
$url = 'https://jsonplaceholder.typicode.com/users';

// Отправляем GET-запрос и получаем ответ в виде строки
$response = file_get_contents($url);

// Преобразуем JSON-строку в массив PHP
$users = json_decode($response, true);

// Выводим имена всех пользователей
echo "Список пользователей:
";
foreach ($users as $user) {
    echo "- {$user['name']} (Email: {$user['email']})
";
}
?>

Объяснение:

file_get_contents() — читает содержимое по URL
json_decode($response, true) — преобразует JSON в ассоциативный массив (второй параметр true означает, что мы хотим получить массив, а не объект)
Мы проходим по массиву циклом и выводим данные

Пример 2: GET-запрос с cURL и обработкой ошибок

<?php
/**
 * Пример 2: GET-запрос с cURL, проверка статуса и обработка ошибок
 */

// Инициализируем сессию cURL
$ch = curl_init();

// Устанавливаем URL
curl_setopt($ch, CURLOPT_URL, 'https://jsonplaceholder.typicode.com/posts/1');

// Просим вернуть результат, а не выводить его
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Устанавливаем таймаут в 10 секунд (чтобы скрипт не завис навсегда)
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

// Выполняем запрос
$response = curl_exec($ch);

// Получаем HTTP-код ответа
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// Проверяем, были ли ошибки соединения
if (curl_errno($ch)) {
    die('Ошибка соединения: ' . curl_error($ch));
}

// Проверяем HTTP-код
if ($httpCode !== 200) {
    die("Ошибка HTTP: сервер вернул код $httpCode");
}

// Закрываем сессию
curl_close($ch);

// Преобразуем JSON в массив
$post = json_decode($response, true);

// Выводим заголовок поста
echo "Заголовок: {$post['title']}
";
echo "Текст: {$post['body']}
";
?>

Объяснение:

curl_init() — создаёт новый ресурс cURL
curl_setopt() — устанавливает опции (их десятки, мы используем основные)
CURLOPT_RETURNTRANSFER — если true, результат возвращается как строка
CURLOPT_TIMEOUT — максимальное время выполнения запроса
curl_getinfo() — получает информацию о выполненном запросе
curl_errno() и curl_error() — проверка на ошибки

Пример 3: POST-запрос с отправкой JSON

<?php
/**
 * Пример 3: POST-запрос для создания нового поста
 * Отправляем данные в формате JSON
 */

// Данные, которые мы хотим отправить
$data = [
    'title' => 'Мой новый пост',
    'body' => 'Это содержимое поста, которое я создаю через API',
    'userId' => 1
];

// Преобразуем массив в JSON-строку
$jsonData = json_encode($data);

// Инициализируем cURL
$ch = curl_init();

// Устанавливаем URL
curl_setopt($ch, CURLOPT_URL, 'https://jsonplaceholder.typicode.com/posts');

// Говорим, что это POST-запрос
curl_setopt($ch, CURLOPT_POST, true);

// Передаём данные
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);

// Устанавливаем заголовки
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',  // Говорим, что отправляем JSON
    'Content-Length: ' . strlen($jsonData)  // Указываем длину данных
]);

// Возвращаем результат
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Выполняем запрос
$response = curl_exec($ch);

// Проверяем HTTP-код
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($httpCode !== 201) {  // 201 Created — успешное создание
    die("Ошибка: сервер вернул код $httpCode");
}

curl_close($ch);

// Выводим ответ сервера (он вернёт созданный объект с ID)
$result = json_decode($response, true);
echo "Пост создан! ID: {$result['id']}
";
?>

Объяснение:

CURLOPT_POST — устанавливает метод POST
CURLOPT_POSTFIELDS — тело запроса (данные)
CURLOPT_HTTPHEADER — массив заголовков
Content-Type: application/json — сообщает серверу, что мы отправляем JSON
Код 201 означает, что ресурс успешно создан

Пример 4: PUT-запрос для обновления данных

<?php
/**
 * Пример 4: PUT-запрос для полного обновления поста
 */

$data = [
    'id' => 1,
    'title' => 'Обновлённый заголовок',
    'body' => 'Новое содержимое поста',
    'userId' => 1
];

$jsonData = json_encode($data);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://jsonplaceholder.typicode.com/posts/1');

// Устанавливаем метод PUT
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($jsonData)
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($httpCode !== 200) {
    die("Ошибка обновления: код $httpCode");
}

curl_close($ch);

$result = json_decode($response, true);
echo "Пост обновлён! Новый заголовок: {$result['title']}
";
?>

Объяснение:

CURLOPT_CUSTOMREQUEST — позволяет установить любой HTTP-метод (PUT, DELETE, PATCH)
PUT обычно требует полного обновления ресурса (все поля)
Код 200 означает успешное выполнение

Пример 5: DELETE-запрос

<?php
/**
 * Пример 5: DELETE-запрос для удаления поста
 */

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://jsonplaceholder.typicode.com/posts/1');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($httpCode !== 200) {
    die("Ошибка удаления: код $httpCode");
}

curl_close($ch);

echo "Пост успешно удалён!
";
?>

Объяснение:

DELETE-запросы обычно не требуют тела запроса
Сервер может вернуть 200 (с подтверждением) или 204 (без содержимого)

Пример 6: Работа с авторизацией (API-ключ)

<?php
/**
 * Пример 6: Запрос с авторизацией через API-ключ
 * Многие API требуют аутентификации
 */

$apiKey = 'ваш_секретный_ключ';  // В реальном проекте храните в .env файле!
$city = 'Moscow';

$ch = curl_init();

// Пример с OpenWeatherMap API
curl_setopt($ch, CURLOPT_URL, "https://api.openweathermap.org/data/2.5/weather?q=$city&appid=$apiKey&units=metric&lang=ru");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($httpCode !== 200) {
    die("Ошибка получения погоды: код $httpCode");
}

curl_close($ch);

$weather = json_decode($response, true);

echo "Погода в {$weather['name']}:
";
echo "Температура: {$weather['main']['temp']}°C
";
echo "Описание: {$weather['weather'][0]['description']}
";
echo "Влажность: {$weather['main']['humidity']}%
";
?>

Объяснение:

API-ключ часто передаётся как параметр URL (appid=$apiKey) или в заголовке
Никогда не храните ключи прямо в коде! Используйте переменные окружения
Параметр units=metric просит вернуть температуру в градусах Цельсия

Пример 7: Использование Guzzle (современный подход)

<?php
/**
 * Пример 7: Работа с API через Guzzle HTTP Client
 * Требуется установка: composer require guzzlehttp/guzzle
 */

require 'vendor/autoload.php';

use GuzzleHttpClient;
use GuzzleHttpExceptionRequestException;

// Создаём клиент с базовыми настройками
$client = new Client([
    'base_uri' => 'https://jsonplaceholder.typicode.com',
    'timeout'  => 10.0,
]);

try {
    // GET-запрос
    $response = $client->get('/users');
    $users = json_decode($response->getBody(), true);
    
    echo "Пользователи (Guzzle):
";
    foreach ($users as $user) {
        echo "- {$user['name']} из города {$user['address']['city']}
";
    }
    
    // POST-запрос
    $response = $client->post('/posts', [
        'json' => [
            'title' => 'Пост через Guzzle',
            'body' => 'Этот пост создан с помощью Guzzle HTTP Client',
            'userId' => 1
        ]
    ]);
    
    $newPost = json_decode($response->getBody(), true);
    echo "
Создан пост с ID: {$newPost['id']}
";
    
} catch (RequestException $e) {
    echo "Ошибка запроса: " . $e->getMessage() . "
";
    if ($e->hasResponse()) {
        echo "HTTP код: " . $e->getResponse()->getStatusCode() . "
";
    }
}
?>

Объяснение:

base_uri — базовый URL, к которому добавляются относительные пути
timeout — максимальное время ожидания
Метод get() и post() возвращают объект ответа
Опция 'json' автоматически преобразует массив в JSON и устанавливает заголовки
Исключения (Exception) позволяют красиво обрабатывать ошибки

Сравнение с Python: чем похоже и чем отличается

Если вы знакомы с Python, вам будет легче понять PHP. Давайте сравним оба языка в контексте работы с HTTP API.

Аспект	PHP	Python
Встроенные средства	file_get_contents(), cURL	urllib.request, http.client
Популярная библиотека	Guzzle	Requests
Синтаксис GET-запроса	`$client->get('/url')`	`requests.get('/url')`
Работа с JSON	`json_decode()`, `json_encode()`	`json.loads()`, `json.dumps()`
Обработка ошибок	Проверка curl_errno(), try-catch (Guzzle)	try-except (исключения)
Асинхронность	Сложнее (через расширения)	asyncio + aiohttp

Пример на Python для сравнения

# Python-версия GET-запроса (аналог примера 1 на PHP)
import requests

url = 'https://jsonplaceholder.typicode.com/users'
response = requests.get(url)

if response.status_code == 200:
    users = response.json()  # Автоматически парсит JSON
    for user in users:
        print(f"- {user['name']} (Email: {user['email']})")
else:
    print(f"Ошибка: {response.status_code}")

Ключевые отличия:

В Python библиотека Requests считается стандартом де-факто, в PHP — Guzzle
Python более лаконичен: response.json() вместо json_decode($response, true)
PHP требует больше ручной настройки (особенно cURL), но даёт больше контроля
В Python исключения используются чаще, в PHP — проверка кодов возврата

Типичные ошибки и подводные камни

1. Игнорирование кодов статуса

Самая частая ошибка новичков — не проверять HTTP-код ответа. Сервер может вернуть 404 (не найдено) или 500 (ошибка), а вы будете пытаться обработать пустой или некорректный ответ.

⚠️ Всегда проверяйте HTTP-код! Даже если API работал вчера, сегодня он может вернуть ошибку.

2. Неправильная обработка JSON

Иногда API возвращает не JSON, а HTML или просто текст с ошибкой. Если вы попытаетесь распарсить такой ответ, PHP выдаст ошибку или вернёт null.

// Неправильно:
$data = json_decode($response, true);
echo $data['name']; // Ошибка! $data может быть null

// Правильно:
$data = json_decode($response, true);
if ($data === null && json_last_error() !== JSON_ERROR_NONE) {
    die('Ошибка парсинга JSON: ' . json_last_error_msg());
}

3. Забытые таймауты

Если сервер не отвечает, ваш скрипт может зависнуть на неопределённое время. Всегда устанавливайте таймаут.

// cURL
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

// Guzzle
$client = new Client(['timeout' => 10.0]);

4. Проблемы с SSL-сертификатами

При работе с HTTPS иногда возникают ошибки из-за неправильных или самоподписанных сертификатов. Никогда не отключайте проверку SSL в production!

// ПЛОХОЙ пример (только для разработки!):
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);

// ХОРОШИЙ пример:
curl_setopt($ch, CURLOPT_CAINFO, '/path/to/cacert.pem');

5. Неправильные заголовки

Многие API требуют определённые заголовки. Например, для JSON API нужно указывать Content-Type: application/json и Accept: application/json.

6. Игнорирование лимитов запросов (Rate Limiting)

Большинство API ограничивают количество запросов в минуту/час. Если превысить лимит, сервер вернёт код 429 (Too Many Requests).

7. Хранение секретов в коде

Никогда не пишите API-ключи и пароли прямо в PHP-файлах! Используйте переменные окружения или файлы конфигурации.

// ПЛОХО:
$apiKey = 'sk-1234567890abcdef';

// ХОРОШО:
$apiKey = getenv('API_KEY'); // Берём из переменной окружения

Лучшие практики и советы профессионалов

1. Используйте Guzzle для серьёзных проектов

Хотя cURL даёт полный контроль, Guzzle предоставляет более чистый и безопасный API. Он автоматически обрабатывает многие подводные камни.

2. Создавайте классы-обёртки для API

Вместо того чтобы разбрасывать вызовы API по всему коду, создайте отдельный класс для каждого внешнего сервиса.

class WeatherAPI {
    private $client;
    private $apiKey;
    
    public function __construct($apiKey) {
        $this->client = new Client(['base_uri' => 'https://api.openweathermap.org/']);
        $this->apiKey = $apiKey;
    }
    
    public function getWeather($city) {
        $response = $this->client->get('/data/2.5/weather', [
            'query' => [
                'q' => $city,
                'appid' => $this->apiKey,
                'units' => 'metric',
                'lang' => 'ru'
            ]
        ]);
        
        return json_decode($response->getBody(), true);
    }
}

// Использование:
$weatherAPI = new WeatherAPI(getenv('WEATHER_API_KEY'));
$weather = $weatherAPI->getWeather('Moscow');

3. Обрабатывайте ошибки gracefully

Не давайте пользователю видеть технические ошибки. Используйте try-catch и показывайте понятные сообщения.

4. Кэшируйте ответы API

Если данные меняются нечасто (например, курс валют), кэшируйте их на несколько минут. Это снизит нагрузку на API и ускорит ваш сайт.

// Простое кэширование в файл
$cacheFile = 'cache/weather_moscow.json';
$cacheTime = 300; // 5 минут

if (file_exists($cacheFile) && (time() - filemtime($cacheFile) < $cacheTime)) {
    $weather = json_decode(file_get_contents($cacheFile), true);
} else {
    $weather = $weatherAPI->getWeather('Moscow');
    file_put_contents($cacheFile, json_encode($weather));
}

5. Логируйте запросы и ошибки

В production всегда логируйте важные запросы к API и возникающие ошибки. Это поможет быстро найти проблему.

6. Используйте PSR-18 (HTTP Client)

PSR-18 — это стандарт PHP для HTTP-клиентов. Если вы используете библиотеки, совместимые с PSR-18, их можно легко заменять.

7.

← 上一课 PHP中的多线程与异步编程：详细指南下一步 → PHP中的代码测试：详细指南