GraphQL API com PHP: tutorial prático passo a passo

GraphQL API com PHP: tutorial prático passo a passo

GraphQL é uma linguagem de consulta para APIs que permite aos clientes obter apenas os dados de que realmente precisam. Ao contrário do REST, onde cada endpoint retorna uma estrutura fixa, o GraphQL oferece flexibilidade e eficiência. Neste tutorial, criaremos uma API GraphQL completa em PHP do zero — desde a instalação das bibliotecas até o processamento de consultas e mutações.

Por que GraphQL e PHP são uma excelente combinação?

O PHP continua sendo uma das linguagens mais populares para desenvolvimento backend. Com a biblioteca webonyx/graphql-php, você pode integrar facilmente o GraphQL em qualquer projeto — desde um blog simples até um CRM complexo. Principais vantagens:

• Flexibilidade de consultas — o cliente decide quais campos obter.
• Ponto único de entrada — em vez de múltiplos endpoints, um único /graphql.
• Tipagem forte — o schema define todos os tipos e relações.
• Facilidade para o frontend — React, Vue e outros frameworks trabalham facilmente com GraphQL.

Implementação passo a passo de uma API GraphQL em PHP

1. Instalação e configuração do ambiente

Para começar, vamos criar um novo projeto e instalar a biblioteca principal via Composer:

composer require webonyx/graphql-php

Também precisaremos de um manipulador HTTP compatível com PSR-7. Usaremos guzzlehttp/psr7 e nyholm/psr7-server:

composer require guzzlehttp/psr7 nyholm/psr7-server

Criaremos a estrutura básica de pastas:

project/├── src/│   ├── Schema/│   ├── Resolvers/│   └── Types/├── public/│   └── index.php├── vendor/└── composer.json

2. Definição do schema GraphQL

O schema é o coração da API GraphQL. Ele descreve os tipos de dados e as operações disponíveis. Vamos criar o arquivo src/Schema/Schema.php:

<?phpnamespace App\\Schema;

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

class Schema{    public static function build(): GraphQLSchema    {        // Tipo "User"        $userType = new ObjectType([            'name' => 'User',            'fields' => [                'id' => Type::int(),                'name' => Type::string(),                'email' => Type::string(),            ]        ]);

        // Tipo "Query" — consulta raiz        $queryType = new ObjectType([            'name' => 'Query',            'fields' => [                'user' => [                    'type' => $userType,                    'args' => [                        'id' => Type::nonNull(Type::int())                    ],                    'resolve' => function ($root, $args) {                        // Aqui estará o resolver                        return UserResolver::getUser($args['id']);                    }                ],                'users' => [                    'type' => Type::listOf($userType),                    'resolve' => function () {                        return UserResolver::getAllUsers();                    }                ]            ]        ]);

        // Tipo "Mutation" — mutação raiz        $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 UserResolver::createUser($args['name'], $args['email']);                    }                ]            ]        ]);

        return new GraphQLSchema([            'query' => $queryType,            'mutation' => $mutationType        ]);    }}