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

Introdução ao GraphQL com PHP: por que vale a pena experimentar

GraphQL é uma linguagem moderna de consulta para APIs, desenvolvida pelo Facebook. Ao contrário do REST, onde cada endpoint retorna uma estrutura de dados fixa, o GraphQL permite que o cliente solicite apenas os campos de que precisa. Isso reduz o volume de dados transmitidos e simplifica o desenvolvimento de aplicações complexas.

Neste tutorial, criaremos uma API GraphQL completa em PHP usando a biblioteca webonyx/graphql-php. Você aprenderá como definir o esquema, escrever resolvers, processar consultas e mutações, além de testar a API através do GraphiQL.

Pressupõe-se que você tenha PHP 8.0+ e Composer instalados. Caso contrário, comece instalando-os.

Instalação e configuração do projeto

Passo 1: Criando o projeto e instalando dependências

Crie um novo diretório para o projeto e inicialize o Composer:

mkdir graphql-php-tutorial\ncd graphql-php-tutorial\ncomposer init

Instale a biblioteca webonyx/graphql-php:

composer require webonyx/graphql-php

Instale também o nikic/fast-route para roteamento simples (opcional, mas conveniente):

composer require nikic/fast-route

Passo 2: Estrutura do projeto

Crie a seguinte estrutura de pastas:

graphql-php-tutorial/\n├── src/\n│   ├── Schema/\n│   │   └── schema.php\n│   ├── Resolvers/\n│   │   ├── QueryResolver.php\n│   │   └── MutationResolver.php\n│   └── Data/\n│       └── Database.php\n├── public/\n│   └── index.php\n├── vendor/\n└── composer.json

Criando o esquema GraphQL

Passo 3: Definindo tipos e esquema

Vamos criar um modelo de dados simples: usuário (User) e postagem (Post). Abra src/Schema/schema.php e adicione o seguinte código:

<?php\n\nnamespace App\\Schema;\n\nuse GraphQL\\Type\\Definition\\ObjectType;\nuse GraphQL\\Type\\Definition\\Type;\nuse GraphQL\\Type\\Schema as GraphQLSchema;\n\nclass Schema\n{\n    public static function build(): GraphQLSchema\n    {\n        // Tipo User\n        $userType = new ObjectType([\n            'name' => 'User',\n            'fields' => [\n                'id' => Type::int(),\n                'name' => Type::string(),\n                'email' => Type::string(),\n                'posts' => [\n                    'type' => Type::listOf(function() use (&$postType) {\n                        return $postType;\n                    }),\n                    'resolve' => function($user) {\n                        return \\App\\Resolvers\\QueryResolver::getPostsByUser($user['id']);\n                    }\n                ]\n            ]\n        ]);\n\n        // Tipo Post\n        $postType = new ObjectType([\n            'name' => 'Post',\n            'fields' => [\n                'id' => Type::int(),\n                'title' => Type::string(),\n                'content' => Type::string(),\n                'author' => [\n                    'type' => $userType,\n                    'resolve' => function($post) {\n                        return \\App\\Resolvers\\QueryResolver::getUserById($post['author_id']);\n                    }\n                ]\n            ]\n        ]);\n\n        // Tipo raiz Query\n        $queryType = new ObjectType([\n            'name' => 'Query',\n            'fields' => [\n                'users' => [\n                    'type' => Type::listOf($userType),\n                    'resolve' => function() {\n                        return \\App\\Resolvers\\QueryResolver::getAllUsers();\n                    }\n                ],\n                'user' => [\n                    'type' => $userType,\n                    'args' => [\n                        'id' => Type::nonNull(Type::int())\n                    ]