GraphQL en PHP: Guía completa de la biblioteca webonyx/graphql-php

Biblioteca GraphQL PHP: webonyx/graphql-php

GraphQL es un lenguaje de consultas moderno para APIs, desarrollado por Facebook. En PHP, una de las bibliotecas más populares y maduras para implementar GraphQL es webonyx/graphql-php. Esta biblioteca permite a los desarrolladores crear APIs flexibles, tipadas y eficientes que brindan a los clientes la posibilidad de solicitar solo los datos necesarios.

En este artículo, veremos en detalle cómo instalar, configurar y usar webonyx/graphql-php en tu proyecto PHP. La biblioteca implementa completamente la especificación oficial de GraphQL (Junio 2018) y admite todas las funcionalidades modernas: consultas (queries), mutaciones (mutations), suscripciones (subscriptions), interfaces, uniones y mucho más.

Instalación y configuración

La instalación se realiza a través de Composer. Abre la terminal en la raíz de tu proyecto y ejecuta:

composer require webonyx/graphql-php

Después de la instalación, la biblioteca está lista para usar. No se requiere configuración mínima: simplemente importa las clases necesarias en tu archivo PHP.

Componentes principales de la biblioteca

La biblioteca consta de varios componentes clave que interactúan entre sí:

• Esquema (Schema) — define los tipos de datos y las operaciones disponibles (consultas y mutaciones).
• Tipos (Types) — describen la estructura de los datos (ObjectType, ScalarType, EnumType, InterfaceType, UnionType, etc.).
• Resolutores (Resolvers) — funciones que devuelven datos para cada campo.
• Ejecutor (Executor) — procesa la solicitud entrante y devuelve el resultado.

Creación de un esquema simple

Veamos un ejemplo de creación de un esquema GraphQL simple para trabajar con usuarios. Primero, definimos el tipo User:

<?phpuse GraphQL\\Type\\Definition\\ObjectType;use GraphQL\\Type\\Definition\\Type;

$userType = new ObjectType([    'name' => 'User',    'fields' => [        'id' => Type::int(),        'name' => Type::string(),        'email' => Type::string(),        'age' => Type::int(),    ],]);

Ahora creamos el tipo de consulta raíz Query, que devolverá una lista de usuarios:

$queryType = new ObjectType([    'name' => 'Query',    'fields' => [        'users' => [            'type' => Type::listOf($userType),            'resolve' => function ($root, $args) {                // Aquí normalmente se consulta la base de datos                return [                    ['id' => 1, 'name' => 'Iván Ivanov', 'email' => 'ivan@example.com', 'age' => 30],                    ['id' => 2, 'name' => 'María Petrova', 'email' => 'maria@example.com', 'age' => 25],                ];            },        ],        'user' => [            'type' => $userType,            'args' => [                'id' => Type::nonNull(Type::int()),            ],            'resolve' => function ($root, $args) {                // Búsqueda de usuario por ID                $users = [                    1 => ['id' => 1, 'name' => 'Iván Ivanov', 'email' => 'ivan@example.com', 'age' => 30],                    2 => ['id' => 2, 'name' => 'María Petrova', 'email' => 'maria@example.com', 'age' => 25],                ];                return $users[$args['id']] ?? null;            },        ],    ],]);

Combinación en un esquema y ejecución de consulta

Ahora combinamos todo en un solo esquema y ejecutamos una consulta de prueba:

use GraphQL\\GraphQL;use GraphQL\\Schema;

$schema = new Schema([    'query' => $queryType,]);

// Consulta GraphQL entrante (normalmente llega en POST)$query = '{ users { id name em