GraphQL em PHP: Guia Completo da Biblioteca webonyx/graphql-php

Biblioteca GraphQL PHP: webonyx/graphql-php

GraphQL é uma linguagem de consulta moderna para APIs, desenvolvida pelo Facebook. Em PHP, uma das bibliotecas mais populares e maduras para implementar GraphQL é a webonyx/graphql-php. Esta biblioteca permite que desenvolvedores criem APIs flexíveis, tipadas e eficientes, que dão aos clientes a capacidade de solicitar apenas os dados necessários.

Neste artigo, veremos em detalhes como instalar, configurar e usar o webonyx/graphql-php no seu projeto PHP. A biblioteca implementa completamente a especificação oficial do GraphQL (Junho de 2018) e suporta todos os recursos modernos: consultas (queries), mutações (mutations), assinaturas (subscriptions), interfaces, uniões e muito mais.

Instalação e configuração

A instalação é feita via Composer. Abra o terminal na raiz do seu projeto e execute:

composer require webonyx/graphql-php

Após a instalação, a biblioteca está pronta para uso. Nenhuma configuração mínima é necessária — basta importar as classes necessárias no seu arquivo PHP.

Componentes principais da biblioteca

A biblioteca consiste em vários componentes-chave que interagem entre si:

• Esquema (Schema) — define os tipos de dados e as operações disponíveis (consultas e mutações).
• Tipos (Types) — descrevem a estrutura dos dados (ObjectType, ScalarType, EnumType, InterfaceType, UnionType, etc.).
• Resolvers (Resolvers) — funções que retornam dados para cada campo.
• Executor (Executor) — processa a consulta recebida e retorna o resultado.

Criando um esquema simples

Vamos considerar um exemplo de criação de um esquema GraphQL simples para trabalhar com usuários. Primeiro, definimos o tipo User:

<?phpuse 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(),    ],]);

Agora, criamos o tipo de consulta raiz Query, que retornará uma lista de usuários:

$queryType = new ObjectType([    'name' => 'Query',    'fields' => [        'users' => [            'type' => Type::listOf($userType),            'resolve' => function ($root, $args) {                // Aqui normalmente uma consulta ao banco de dados                return [                    ['id' => 1, 'name' => 'Ivan Ivanov', 'email' => 'ivan@example.com', 'age' => 30],                    ['id' => 2, 'name' => 'Maria Petrova', 'email' => 'maria@example.com', 'age' => 25],                ];            },        ],        'user' => [            'type' => $userType,            'args' => [                'id' => Type::nonNull(Type::int()),            ],            'resolve' => function ($root, $args) {                // Busca de usuário por ID                $users = [                    1 => ['id' => 1, 'name' => 'Ivan Ivanov', 'email' => 'ivan@example.com', 'age' => 30],                    2 => ['id' => 2, 'name' => 'Maria Petrova', 'email' => 'maria@example.com', 'age' => 25],                ];                return $users[$args['id']] ?? null;            },        ],    ],]);

Unindo em um esquema e executando uma consulta

Agora, unimos tudo em um único esquema e executamos uma consulta de teste:

use GraphQL\\GraphQL;use GraphQL\\Schema;

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

// Consulta GraphQL recebida (geralmente vem via POST)$query = '{ users { id name em