API GraphQL con PHP: tutorial paso a paso para principiantes

Introducción a GraphQL y PHP

GraphQL es un lenguaje de consultas para API, desarrollado por Facebook, que permite a los clientes solicitar únicamente los datos que realmente necesitan. A diferencia de REST, donde cada endpoint devuelve una estructura de datos fija, GraphQL ofrece flexibilidad y eficiencia. Si trabajas con PHP y deseas implementar una API moderna, este tutorial es para ti.

En esta guía crearemos una API GraphQL simple pero funcional utilizando la librería webonyx/graphql-php. Aprenderás cómo instalar dependencias, definir el schema, tipos, resolvers y procesar consultas. Los ejemplos de código te ayudarán a comenzar rápidamente.

1. Preparación del entorno e instalación de dependencias

Para empezar, asegúrate de tener instalado PHP versión 7.4 o superior y Composer, el gestor de dependencias para PHP. Si aún no tienes Composer, descárgalo desde el sitio oficial.

Crea un nuevo proyecto e instala la librería webonyx/graphql-php:

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

Después de la instalación, en la carpeta del proyecto aparecerán el directorio vendor y el archivo composer.json. También crea el archivo index.php — ahí estará todo nuestro código.

Adicionalmente, para facilitar el trabajo con solicitudes HTTP, instala laminas/laminas-diactoros (una implementación popular de PSR-7) y laminas/laminas-httphandlerrunner:

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

2. Definición del schema y tipos de GraphQL

El corazón de cualquier API GraphQL es el schema. Describe qué datos están disponibles y cómo se pueden consultar. En nuestro ejemplo, crearemos un modelo simple de "Usuario" (User) y "Publicación" (Post).

Primero, definimos los tipos usando la clase GraphQL\\Type\\Definition\\ObjectType. Crea el archivo schema.php (o agrega el código directamente en 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;

// Definimos el tipo User$userType = new ObjectType([    'name' => 'User',    'description' => 'Representa un usuario del sistema',    'fields' => [        'id' => Type::int(),        'name' => Type::string(),        'email' => Type::string(),    ]]);

// Definimos el tipo Post$postType = new ObjectType([    'name' => 'Post',    'description' => 'Publicación de un usuario',    'fields' => [        'id' => Type::int(),        'title' => Type::string(),        'content' => Type::string(),        'author' => $userType, // Relación con el usuario    ]]);

Observa: usamos Type::int() y Type::string() — estos son tipos escalares incorporados de GraphQL. El campo author hace referencia a otro tipo objeto, lo que permite construir consultas anidadas.

3. Creación de resolvers y datos ficticios

Los resolvers son funciones que devuelven datos para cada campo. En el caso más simple, podemos usar datos ficticios (arrays).

Agreguemos resolvers para el tipo raíz Query. A través de él, los clientes obtendrán los datos.

// Datos ficticios$users = [    1 => ['id' => 1, 'name' => 'Iván Petrov', 'email' => 'ivan@example.com'],    2 => ['id' => 2, 'name' => 'María Smirnova', 'email' => 'maria@example.com'],];

$posts = [    1 => ['id' => 1, 'title' => 'Primera entrada', 'content' => 'Texto de la primera entrada', 'author_id' => 1],