API GraphQL con PHP: tutorial paso a paso

Introducción: Por qué GraphQL y PHP son una excelente combinación

En el mundo del desarrollo web, la API REST ha sido durante mucho tiempo el estándar de facto. Sin embargo, con el aumento de la complejidad de las aplicaciones y la aparición de clientes móviles, las desventajas de REST se han vuelto evidentes: exceso o falta de datos, múltiples endpoints, versionado complejo. GraphQL, desarrollado por Facebook, resuelve estos problemas al permitir que el cliente solicite solo los datos que necesita y los reciba en una sola consulta.

PHP, a pesar de ser de la "vieja escuela", sigue siendo un lenguaje potente para crear lógica de servidor. Gracias a bibliotecas modernas como webonyx/graphql-php, implementar una API GraphQL en PHP se ha vuelto simple y eficiente. En este tutorial, crearemos paso a paso un servidor GraphQL completo que pueda manejar consultas, mutaciones y trabajar con una base de datos.

Usaremos PHP 8.0+, Composer para la gestión de dependencias y el servidor integrado de PHP para pruebas locales. Al final del artículo, podrás desplegar tu propia API e integrarla con cualquier frontend.

1. Instalación y configuración del entorno

Antes de escribir código, es necesario preparar el proyecto. Asegúrate de tener instalados PHP 8.0+ y Composer. Crea una nueva carpeta para el proyecto y accede a ella:

mkdir graphql-php-tutorialcd graphql-php-tutorial

Ahora instala la biblioteca principal webonyx/graphql-php usando Composer:

composer require webonyx/graphql-php

Para trabajar con la base de datos, usaremos PDO, que está integrado en PHP. Adicionalmente, instalaremos una biblioteca para el análisis conveniente de consultas:

composer require graphql-php/graphql-php

Crea el archivo index.php — este será el punto de entrada de nuestra aplicación. Configura la autocarga de Composer y la estructura básica:

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

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

// Aquí estará nuestra lógica

También crea un archivo schema.graphql para almacenar el esquema en formato de texto (opcional, pero útil para proyectos grandes).

2. Definición del esquema y tipos de datos

El corazón de cualquier API GraphQL es el esquema. Describe qué datos están disponibles y cómo acceder a ellos. En nuestro ejemplo, crearemos un modelo simple de usuario (User) y publicación (Post).

Comencemos con la definición de tipos. En el archivo index.php, agrega las siguientes clases:

// Tipo User$userType = new ObjectType([    'name' => 'User',    'fields' => [        'id' => Type::int(),        'name' => Type::string(),        'email' => Type::string(),        'posts' => [            'type' => Type::listOf($postType),            'resolve' => function ($user) use ($db) {                // Función resolutora para cargar las publicaciones del usuario                $stmt = $db->prepare('SELECT * FROM posts WHERE user_id = :id');                $stmt->execute([':id' => $user['id']]);                return $stmt->fetchAll(PDO::FETCH_ASSOC);            }        ]    ]]);

// Tipo Post$postType = new ObjectType([    'name' => 'Post',    'fields' => [        'id' => Type::int(),        'title' => Type::string(),        'content' => Type::string(),        'author' => [            'type' => $userType,            'resolve' => function ($post) use ($db) {                $stmt = $db->prepare('SELECT * FROM users WHERE id = :id');                $stmt->execute([':id' => $post['user_id']]);                return $stmt->fetch(PDO::FETCH_ASSOC);            }        ]    ]]);

Presta atención a los resolutores — son funciones que determinan cómo obtener los datos para cada campo. En el ejemplo anterior, usamos PDO para las consultas a la base de datos.

Ahora crea