Download the PHP package wappcode/gqlpdss without Composer

GQLPDSS-lib

Una librería PHP moderna para crear APIs GraphQL escalables con Doctrine ORM, arquitectura modular y funcionalidades avanzadas como DataLoaders y middleware.

📚 Documentación Completa

Para información detallada, visita: Quick Start Guide

✨ Características Principales

• 🚀 API GraphQL completa
• 🏗️ Arquitectura modular flexible y escalable
• 🔄 Resolvers automáticos para operaciones CRUD con Doctrine ORM
• ⚡ DataLoaders integrados para prevenir el problema N+1
• 🔧 Middleware pipeline para lógica transversal (auth, logging, cache)
• 📄 Paginación estilo Relay con cursor-based pagination
• 🎯 Tipos GraphQL personalizados (DateTime, Date, JSON)
• 🐳 Entorno Docker preconfigurado para desarrollo
• 📋 Sistema de filtros avanzado con múltiples operadores

🛠️ Instalación

Usar Composer

1. Crear nuevo proyecto

2. Instalar la librería

O agregar al composer.json:

3. Estructura del proyecto

Crea la siguiente estructura de directorios:

⚙️ Configuración

1. Configurar el módulo principal

Crear modules/AppModule/config/module.config.php

Crear modules/AppModule/src/AppModule.php

Configurar el autoload en composer.json

2. Archivos de configuración

Crear config/master.config.php

Crear config/doctrine.entities.php

Crear config/doctrine.local.php

Crear public/index.php

Parámetro baseHref

El parámetro baseHref del constructor de Application define el prefijo de ruta bajo el que está montada la aplicación dentro del servidor web. Es el equivalente a indicar en qué "subcarpeta" vive tu index.php dentro del dominio.

Solo es necesario cuando la raíz del sitio no coincide con la raíz del dominio. Si tu aplicación responde directamente en https://midominio.com/, no hace falta configurarlo.

Cuándo usarlo: cuando el index.php está publicado en una ruta distinta a /. Por ejemplo, si tu app está accesible en https://midominio.com/mi-app/public, el router necesita saber que debe ignorar el prefijo /mi-app/public al resolver las rutas internas.

Sin baseHref, el router incluiría el prefijo /mi-app en la ruta que intenta resolver, por lo que ninguna ruta ni endpoint GraphQL coincidiría correctamente.

Crear cli-config.php (para comandos Doctrine CLI)

💾 Trabajando con Entidades Doctrine

Ejemplo de Entidad User

Crear modules/AppModule/src/Entities/User.php:

Comandos Doctrine útiles

🚀 Ejecutar la aplicación

Desarrollo local

Endpoints disponibles

• GraphQL API:
  • GET/POST http://localhost:8000/api (desarrollo)
  • POST http://localhost:8000/api (producción)

�️ Rutas REST (Opcional)

Además de GraphQL, puedes definir rutas REST tradicionales en tus módulos.

Definir rutas en el módulo

En el método getRoutes() de tu clase Module, retorna un array de objetos RouteModel:

Parámetros de RouteModel:

• Método HTTP: GET, POST, PUT, DELETE, PATCH, etc.
• Patrón de ruta: Soporta parámetros dinámicos con expresiones regulares
  • {id} - Cualquier valor
  • {id:\d+} - Solo números
  • {id:.+} - Cualquier carácter (uno o más)
  • {slug:[a-z-]+} - Slug con letras minúsculas y guiones
• Clase controlador: Debe extender AbstractAppController

Crear un controlador

Los controladores deben extender GPDCore\Routing\AbstractAppController e implementar el método dispatch():

Métodos útiles del AbstractAppController

Ejemplo completo: CRUD de usuarios con rutas REST

Definir las rutas

Controlador de listado

Controlador de detalle

�📋 Schema GraphQL básico

Crear modules/AppModule/config/schema.graphql:

📚 API Reference

🔧 ResolverFactory

La clase ResolverFactory simplifica la creación de resolvers CRUD automáticos con Doctrine ORM.

Métodos principales

forConnection(string $entityClass, ?QueryModifierInterface $queryModifier = null): callable

Crea un resolver para consultas paginadas estilo Relay Connection con soporte completo para filtros, ordenamiento y joins.

Ejemplo de uso en GraphQL:

forItem(string $entityClass): callable

Crea un resolver para obtener un único elemento por ID.

forCreate(string $entityClass): callable

Crea un resolver para operaciones de creación con validación automática.

forUpdate(string $entityClass): callable

Crea un resolver para operaciones de actualización.

forDelete(string $entityClass): callable

Crea un resolver para operaciones de eliminación (soft delete si está configurado).

Resolvers para relaciones (prevención N+1)

forEntity(DataLoaderInterface $dataLoader, string $fieldName): callable

Crea un resolver para relaciones many-to-one usando DataLoader.

forCollection(string $entityClass, string $fieldName, string $targetEntity, ?QueryModifierInterface $queryModifier = null): callable

Crea un resolver para relaciones one-to-many usando DataLoader.

🔄 ResolverPipelineFactory

Sistema de middleware para resolvers GraphQL que permite aplicar lógica transversal.

Métodos principales

createPipeline(callable $resolver, array $middlewares): callable

Crea un pipeline de middleware para un resolver.

createWrapper(callable $middleware): ResolverPipelineHandlerInterface

Convierte una función middleware en un handler de pipeline.

🔒 ResolverTransactionMiddlewareFactory

Fábrica que crea un middleware de transacción de base de datos listo para usar en pipelines de resolvers. Envuelve la ejecución del resolver dentro de una transacción Doctrine: hace commit si todo va bien y rollback automático si ocurre cualquier excepción.

Método principal

createMiddleware(): ResolverMiddlewareInterface

Crea una instancia de middleware que gestiona transacciones de base de datos automáticamente.

Comportamiento interno

Posición recomendada en el pipeline

El middleware de transacción debe colocarse al final del array de middlewares (última posición). Dado que el pipeline se ejecuta en orden inverso, esto hace que el middleware de transacción sea el primero en ejecutarse, envolviendo así toda la cadena de lógica (validaciones, autorizaciones, etc.) dentro de una única transacción.

⚠️ Nota: Si ResolverFactory::forCreate, forUpdate o forDelete ya gestionan su propia transacción internamente, usar este middleware añadirá una transacción anidada. Esto es seguro en Doctrine siempre que ambas transacciones finalicen correctamente, pero conviene revisar si la gestión de transacciones debe delegarse completamente al middleware.

🎯 Tipos GraphQL personalizados

La librería incluye tipos escalares personalizados listos para usar:

DateTimeType

• Nombre: DateTime
• Descripción: Fecha y hora en formato ISO 8601
• Ejemplo: "2024-01-15T10:30:00Z"

DateType

• Nombre: Date
• Descripción: Fecha en formato ISO (solo fecha)
• Ejemplo: "2024-01-15"

JSONData

• Nombre: JSONData
• Descripción: Datos JSON arbitrarios
• Ejemplo: {"key": "value", "nested": {"data": 123}}

Registro de tipos en módulos

🔍 Sistema de filtros avanzado

La librería incluye un sistema de filtros robusto que soporta operadores complejos, joins y lógica AND/OR.

Operadores disponibles

Ejemplo de filtros complejos

🚀 Ejemplos prácticos

1. API completa de Blog

2. GraphQL Schema completo

📝 Mejores prácticas

1. Organización del código

2. Uso de DataLoaders

4. Manejo de errores

🤝 Contribuir

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/amazing-feature)
3. Commit tus cambios (git commit -m 'Add amazing feature')
4. Push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

🆘 Soporte

• 📖 Documentación completa
• 🐛 Reportar issues
• 💬 Discusiones

¿Te ha sido útil esta librería? ⭐ ¡Danos una estrella en GitHub!