GraphQL API con PHP: tutorial práctico paso a paso

Introducción a GraphQL con PHP: por qué vale la pena probarlo

GraphQL es un lenguaje de consultas moderno para API, desarrollado por Facebook. A diferencia de REST, donde cada endpoint devuelve una estructura de datos fija, GraphQL permite al cliente solicitar solo los campos que necesita. Esto reduce el volumen de datos transferidos y simplifica el desarrollo de aplicaciones complejas.

En este tutorial crearemos una API GraphQL completa en PHP utilizando la biblioteca webonyx/graphql-php. Aprenderás a definir el esquema, escribir resolutores, procesar consultas y mutaciones, y probar la API a través de GraphiQL.

Se asume que tienes instalado PHP 8.0+ y Composer. Si no es así, comienza instalándolos.

Instalación y configuración del proyecto

Paso 1: Creación del proyecto e instalación de dependencias

Crea un nuevo directorio para el proyecto e inicializa Composer:

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

Instala la biblioteca webonyx/graphql-php:

composer require webonyx/graphql-php

También instala nikic/fast-route para enrutamiento simple (opcional, pero conveniente):

composer require nikic/fast-route

Paso 2: Estructura del proyecto

Crea la siguiente estructura de carpetas:

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

Creación del esquema GraphQL

Paso 3: Definición de tipos y esquema

Crearemos un modelo de datos simple: usuario (User) y publicación (Post). Abre src/Schema/schema.php y agrega el siguiente 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 raíz 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                    ]