GraphQL API com PHP: tutorial passo a passo para iniciantes

Introdução ao GraphQL e PHP

GraphQL é uma linguagem de consulta para APIs, desenvolvida pelo Facebook, que permite aos clientes solicitarem apenas os dados de que realmente precisam. Ao contrário do REST, onde cada endpoint retorna uma estrutura de dados fixa, o GraphQL oferece flexibilidade e eficiência. Se você trabalha com PHP e deseja implementar uma API moderna, este tutorial é para você.

Neste guia, criaremos uma API GraphQL simples, porém funcional, utilizando a biblioteca webonyx/graphql-php. Você aprenderá como instalar dependências, definir o schema, tipos, resolvers e processar consultas. Os exemplos de código ajudarão você a começar rapidamente.

1. Preparação do ambiente e instalação de dependências

Para começar, certifique-se de ter o PHP versão 7.4 ou superior instalado e o Composer, o gerenciador de dependências para PHP. Se o Composer ainda não estiver instalado, baixe-o do site oficial.

Crie um novo projeto e instale a biblioteca webonyx/graphql-php:

mkdir graphql-php-tutorialcd graphql-php-tutorialcomposer init --name="myapp/graphql-demo" --type="project" --no-interactioncomposer require webonyx/graphql-php

Após a instalação, o diretório vendor e o arquivo composer.json aparecerão na pasta do projeto. Crie também o arquivo index.php — todo o nosso código estará nele.

Adicionalmente, para facilitar o trabalho com requisições HTTP, instale laminas/laminas-diactoros (uma implementação PSR-7 popular) e laminas/laminas-httphandlerrunner:

composer require laminas/laminas-diactoroscomposer require laminas/laminas-httphandlerrunner

2. Definição do schema e tipos GraphQL

O coração de qualquer API GraphQL é o schema. Ele descreve quais dados estão disponíveis e como podem ser consultados. No nosso exemplo, criaremos um modelo simples de "Usuário" (User) e "Postagem" (Post).

Primeiro, definimos os tipos usando a classe GraphQL\\Type\\Definition\\ObjectType. Crie o arquivo schema.php (ou adicione o código diretamente no index.php).

<?phprequire_once __DIR__ . '/vendor/autoload.php';

use GraphQL\\Type\\Definition\\ObjectType;use GraphQL\\Type\\Definition\\Type;use GraphQL\\Type\\Schema;use GraphQL\\GraphQL;

// Define o tipo User$userType = new ObjectType([    'name' => 'User',    'description' => 'Representa um usuário do sistema',    'fields' => [        'id' => Type::int(),        'name' => Type::string(),        'email' => Type::string(),    ]]);

// Define o tipo Post$postType = new ObjectType([    'name' => 'Post',    'description' => 'Postagem de um usuário',    'fields' => [        'id' => Type::int(),        'title' => Type::string(),        'content' => Type::string(),        'author' => $userType, // Relacionamento com o usuário    ]]);

Observe: usamos Type::int() e Type::string() — estes são tipos escalares embutidos do GraphQL. O campo author referencia outro tipo de objeto, permitindo consultas aninhadas.

3. Criação de resolvers e dados fictícios

Resolvers são funções que retornam dados para cada campo. No caso mais simples, podemos usar dados fictícios (arrays).

Adicionaremos resolvers para o tipo raiz Query. É através dele que os clientes obterão os dados.

// Dados fictícios$users = [    1 => ['id' => 1, 'name' => 'Ivan Petrov', 'email' => 'ivan@example.com'],    2 => ['id' => 2, 'name' => 'Maria Smirnova', 'email' => 'maria@example.com'],];

$posts = [    1 => ['id' => 1, 'title' => 'Primeira postagem', 'content' => 'Texto da primeira postagem', 'author_id' => 1],