GraphQL — это не просто модный тренд, а реальный способ дать клиентам ровно те данные, которые им нужны, без лишних запросов. Если вы пишете на PHP и хотите попробовать GraphQL, но не знаете, с чего начать, эта статья для вас. Разберём на пальцах, как настроить GraphQL в PHP-проекте, создать схему и обработать запросы.
Что такое GraphQL и зачем он нужен в PHP
GraphQL — это язык запросов к API, который позволяет клиенту указать, какие именно поля ему нужны. Вместо того чтобы получать фиксированный набор данных (как в REST), вы запрашиваете только то, что нужно. Это особенно полезно для мобильных приложений с медленным интернетом.
В PHP GraphQL можно реализовать с помощью библиотеки webonyx/graphql-php. Она предоставляет готовый сервер, который парсит запросы и возвращает JSON. Работает быстро и поддерживается сообществом.
Зачем это вам? Если вы устали плодить эндпоинты под каждый чих или клиенты жалуются на избыток данных — GraphQL решит эти проблемы.
Установка и настройка GraphQL в PHP
Начнём с установки библиотеки через Composer. Убедитесь, что у вас есть composer.json (или создайте его командой composer init).
composer require webonyx/graphql-php
После установки создайте файл index.php — это будет точка входа. Внутри подключите автозагрузку и инициализируйте сервер GraphQL.
<?php
require_once __DIR__ . '/vendor/autoload.php';
use GraphQL\GraphQL;
use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;
use GraphQL\Type\Schema;
// Создаём тип Query
$queryType = new ObjectType([
'name' => 'Query',
'fields' => [
'hello' => [
'type' => Type::string(),
'resolve' => function () {
return 'Привет, GraphQL!';
}
]
]
]);
$schema = new Schema([
'query' => $queryType
]);
// Обрабатываем запрос
$rawInput = file_get_contents('php://input');
$input = json_decode($rawInput, true);
$query = $input['query'] ?? '';
$variableValues = $input['variables'] ?? null;
try {
$result = GraphQL::executeQuery($schema, $query, null, null, $variableValues);
$output = $result->toArray();
} catch (\Exception $e) {
$output = ['error' => $e->getMessage()];
}
header('Content-Type: application/json');
echo json_encode($output);
Это минимальный сервер. Теперь если отправить POST-запрос с телом {"query": "{ hello }"}, получите ответ {"data":{"hello":"Привет, GraphQL!"}}.
try-catch при выполнении GraphQL-запросов. Ошибки в схеме или резолверах могут привести к фатальным ошибкам, а так вы вернёте клиенту понятный JSON.
Создание схемы: типы, поля и резолверы
Схема — это сердце GraphQL. Она описывает, какие данные доступны и как их получить. В PHP схема строится из объектов ObjectType, которые содержат поля. Каждое поле имеет тип и функцию-резолвер (кроме скалярных типов).
Допустим, у нас есть база данных с пользователями. Опишем тип User и запрос для получения пользователя по ID.
use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;
$userType = new ObjectType([
'name' => 'User',
'fields' => [
'id' => Type::int(),
'name' => Type::string(),
'email' => Type::string(),
]
]);
$queryType = new ObjectType([
'name' => 'Query',
'fields' => [
'user' => [
'type' => $userType,
'args' => [
'id' => Type::int()
],
'resolve' => function ($root, $args) {
// Здесь должен быть запрос к БД, например через PDO
// Для примера возвращаем массив
$users = [
1 => ['id' => 1, 'name' => 'Иван', 'email' => 'ivan@example.com'],
2 => ['id' => 2, 'name' => 'Мария', 'email' => 'maria@example.com'],
];
return $users[$args['id']] ?? null;
}
]
]
]);
Теперь клиент может запросить только нужные поля: { user(id: 1) { name email } } и получит только имя и email.
Резолверы могут быть асинхронными (возвращать Promise), но в PHP это редкость. Обычно просто возвращают данные.
Обработка запросов и мутации
Кроме запросов на чтение, GraphQL поддерживает мутации — изменения данных. Они описываются так же, как и Query, но в схеме добавляется тип Mutation.
$mutationType = new ObjectType([
'name' => 'Mutation',
'fields' => [
'createUser' => [
'type' => $userType,
'args' => [
'name' => Type::nonNull(Type::string()),
'email' => Type::nonNull(Type::string()),
],
'resolve' => function ($root, $args) {
// Логика сохранения в БД
return ['id' => 3, 'name' => $args['name'], 'email' => $args['email']];
}
]
]
]);
$schema = new Schema([
'query' => $queryType,
'mutation' => $mutationType
]);
Клиент отправляет мутацию так:
mutation {
createUser(name: "Пётр", email: "petr@example.com") {
id
name
}
}
В ответ придёт созданный пользователь с id и name.
query($id: Int!) { user(id: $id) { name } } и передавайте variables: { "id": 1 }.
Полезные советы и сравнение с REST
GraphQL в PHP — это мощно, но не всегда серебряная пуля. Вот несколько рекомендаций, чтобы не наступить на грабли.
- Кэширование: GraphQL-запросы сложнее кэшировать, чем REST. Используйте постоянные запросы (persisted queries) или кэшируйте на уровне резолверов.
- Безопасность: Ограничивайте глубину запросов и сложность, чтобы избежать DoS-атак. В библиотеке webonyx есть настройки для этого.
- Инструменты: Для отладки используйте GraphiQL или Playground — они показывают схему и помогают строить запросы.
Сравним GraphQL и REST в таблице:
| Критерий | GraphQL | REST |
|---|---|---|
| Гибкость запросов | Высокая (клиент выбирает поля) | Фиксированная |
| Количество эндпоинтов | Один | Много |
| Кэширование | Сложнее | Проще (HTTP-кэш) |
| Порог входа | Выше | Ниже |
Выбирайте инструмент под задачу. Если у вас простой API с редкими изменениями — REST может быть проще. Если клиенты требуют гибкости — GraphQL.
Что в итоге
GraphQL в PHP — это реально и не так сложно, как кажется. Библиотека webonyx/graphql-php даёт всё необходимое: парсинг запросов, валидацию, выполнение. Вы описываете схему, пишете резолверы и получаете гибкий API.
Главное — не забывайте про безопасность и кэширование. Начните с простого запроса, постепенно добавляйте мутации и типы. И тогда ваши клиенты скажут спасибо за то, что больше не нужно тянуть лишние данные.
Пробуйте, экспериментируйте, и пусть GraphQL станет вашим другом в мире PHP.



