GraphQL — это не просто модный тренд, а реальный способ дать клиентам ровно те данные, которые им нужны, без лишних запросов. Если вы пишете на PHP и хотите попробовать GraphQL, но не знаете, с чего начать, эта статья для вас. Разберём на пальцах, как настроить GraphQL в PHP-проекте, создать схему и обработать запросы.

Digital-студия WNDER

Что такое 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.

Лайфхак: Используйте переменные в GraphQL-запросах, чтобы не дублировать код и защититься от инъекций. Например: 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.

Студия WNDER