GraphQL API con PHP: tutorial paso a paso en la práctica

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

GraphQL es un lenguaje de consultas para API que permite a los clientes obtener solo los datos que realmente necesitan. A diferencia de REST, donde cada endpoint devuelve una estructura fija, GraphQL ofrece flexibilidad y eficiencia. En este tutorial crearemos una API GraphQL completa en PHP desde cero — desde la instalación de librerías hasta el procesamiento de consultas y mutaciones.

¿Por qué GraphQL y PHP son una excelente combinación?

PHP sigue siendo uno de los lenguajes más populares para el desarrollo backend. Con la librería webonyx/graphql-php puedes integrar fácilmente GraphQL en cualquier proyecto — desde un blog simple hasta un CRM complejo. Las principales ventajas:

• Flexibilidad de consultas — el cliente decide qué campos obtener.
• Un único punto de entrada — en lugar de múltiples endpoints, un solo /graphql.
• Tipado estricto — el esquema define todos los tipos y relaciones.
• Comodidad para el frontend — React, Vue y otros frameworks trabajan fácilmente con GraphQL.

Implementación paso a paso de una API GraphQL en PHP

1. Instalación y configuración del entorno

Para empezar, crearemos un nuevo proyecto e instalaremos la librería principal mediante Composer:

composer require webonyx/graphql-php

También necesitaremos un manejador HTTP compatible con PSR-7. Usaremos guzzlehttp/psr7 y nyholm/psr7-server:

composer require guzzlehttp/psr7 nyholm/psr7-server

Crearemos la estructura básica de carpetas:

project/├── src/│   ├── Schema/│   ├── Resolvers/│   └── Types/├── public/│   └── index.php├── vendor/└── composer.json

2. Definición del esquema GraphQL

El esquema es el corazón de la API GraphQL. Describe los tipos de datos y las operaciones disponibles. Crearemos el archivo src/Schema/Schema.php:

<?phpnamespace App\\Schema;

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

class Schema{    public static function build(): GraphQLSchema    {        // Tipo "User"        $userType = new ObjectType([            'name' => 'User',            'fields' => [                'id' => Type::int(),                'name' => Type::string(),                'email' => Type::string(),            ]        ]);

        // Tipo "Query" — consulta raíz        $queryType = new ObjectType([            'name' => 'Query',            'fields' => [                'user' => [                    'type' => $userType,                    'args' => [                        'id' => Type::nonNull(Type::int())                    ],                    'resolve' => function ($root, $args) {                        // Aquí irá el resolver                        return UserResolver::getUser($args['id']);                    }                ],                'users' => [                    'type' => Type::listOf($userType),                    'resolve' => function () {                        return UserResolver::getAllUsers();                    }                ]            ]        ]);

        // Tipo "Mutation" — mutación raíz        $mutationType = new ObjectType([            'name' => 'Mutation',            'fields' => [                'createUser' => [                    'type' => $userType,                    'args' => [                        'name' => Type::nonNull(Type::string()),                        'email' => Type::nonNull(Type::string())                    ],                    'resolve' => function ($root, $args) {                        return UserResolver::createUser($args['name'], $args['email']);                    }                ]            ]        ]);

        return new GraphQLSchema([