GraphQL в PHP: Полное руководство по библиотеке webonyx/graphql-php

GraphQL библиотека PHP: webonyx/graphql-php

GraphQL — это современный язык запросов для API, разработанный Facebook. В PHP одной из самых популярных и зрелых библиотек для реализации GraphQL является webonyx/graphql-php. Эта библиотека позволяет разработчикам создавать гибкие, типизированные и эффективные API, которые дают клиентам возможность запрашивать только необходимые данные.

В этой статье мы подробно рассмотрим, как установить, настроить и использовать webonyx/graphql-php на вашем PHP-проекте. Библиотека полностью реализует официальную спецификацию GraphQL (June 2018) и поддерживает все современные возможности: запросы (queries), мутации (mutations), подписки (subscriptions), интерфейсы, объединения и многое другое.

Установка и настройка

Установка осуществляется через Composer. Откройте терминал в корне вашего проекта и выполните:

composer require webonyx/graphql-php

После установки библиотека готова к использованию. Минимальная конфигурация не требуется — просто импортируйте нужные классы в ваш PHP-файл.

Основные компоненты библиотеки

Библиотека состоит из нескольких ключевых компонентов, которые взаимодействуют друг с другом:

• Схема (Schema) — определяет типы данных и доступные операции (запросы и мутации).
• Типы (Types) — описывают структуру данных (ObjectType, ScalarType, EnumType, InterfaceType, UnionType и др.).
• Резолверы (Resolvers) — функции, которые возвращают данные для каждого поля.
• Исполнитель (Executor) — обрабатывает входящий запрос и возвращает результат.

Создание простой схемы

Рассмотрим пример создания простой GraphQL схемы для работы с пользователями. Сначала определим тип User:

<?php
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(),
        'age' => Type::int(),
    ],
]);

Теперь создадим корневой тип запросов Query, который будет возвращать список пользователей:

$queryType = new ObjectType([
    'name' => 'Query',
    'fields' => [
        'users' => [
            'type' => Type::listOf($userType),
            'resolve' => function ($root, $args) {
                // Здесь обычно запрос к базе данных
                return [
                    ['id' => 1, 'name' => 'Иван Иванов', 'email' => 'ivan@example.com', 'age' => 30],
                    ['id' => 2, 'name' => 'Мария Петрова', 'email' => 'maria@example.com', 'age' => 25],
                ];
            },
        ],
        'user' => [
            'type' => $userType,
            'args' => [
                'id' => Type::nonNull(Type::int()),
            ],
            'resolve' => function ($root, $args) {
                // Поиск пользователя по ID
                $users = [
                    1 => ['id' => 1, 'name' => 'Иван Иванов', 'email' => 'ivan@example.com', 'age' => 30],
                    2 => ['id' => 2, 'name' => 'Мария Петрова', 'email' => 'maria@example.com', 'age' => 25],
                ];
                return $users[$args['id']] ?? null;
            },
        ],
    ],
]);

Объединение в схему и выполнение запроса

Теперь объединим все в единую схему и выполним тестовый запрос:

use GraphQL\GraphQL;
use GraphQL\Schema;

$schema = new Schema([
    'query' => $queryType,
]);

// Входящий GraphQL запрос (обычно приходит в POST)
$query = '{ users { id name email } }';

try {
    $result = GraphQL::executeQuery($schema, $query);
    $output = $result->toArray();
} catch (\Exception $e) {
    $output = [
        'errors' => [
            ['message' => $e->getMessage()],
        ],
    ];
}

// Возвращаем JSON
header('Content-Type: application/json');
echo json_encode($output);

Результат выполнения будет выглядеть так:

{
  "data": {
    "users": [
      {"id": 1, "name": "Иван Иванов", "email":