README

A framework-agnostic PSR-15 middleware for handling GraphQL requests using webonyx/graphql-php.

Features

• PSR-15 compliant middleware
• Framework agnostic
• Schema caching support
• Request preprocessing capabilities
• Flexible response handling
• Operation-specific resolvers with dependency injection support
• Resolver documentation

Documentation

• Configuration
• Request Preprocessing
• Response Handling
• Resolvers

Installation

composer require xaddax/webonyx-psr15-middleware

Requirements

• PHP 8.3+
• PSR-7 implementation (e.g., nyholm/psr7)
• PSR-17 HTTP factories implementation
• PSR-6 cache implementation (optional, e.g., symfony/cache)

Basic Usage

use GraphQL\Server\ServerConfig; use GraphQL\Type\Schema; use Nyholm\Psr7\Factory\Psr17Factory; use GraphQL\Middleware\Factory\GraphQLMiddlewareFactory; // Create PSR-17 factories $psr17Factory = new Psr17Factory(); // Configure your GraphQL schema and server $serverConfig = new ServerConfig(); $serverConfig->setSchema($schema); // Create the middleware factory $middlewareFactory = new GraphQLMiddlewareFactory( serverConfig: $serverConfig, responseFactory: $psr17Factory, streamFactory: $psr17Factory ); // Create and add the middleware to your application $middleware = $middlewareFactory->createMiddleware();

Schema Generation

The library includes support for generating schemas from .graphql files:

use GraphQL\Middleware\Config\DefaultConfiguration; use GraphQL\Middleware\Factory\GeneratedSchemaFactory; // Configure schema generation $schemaConfig = new DefaultConfiguration([ 'schema' => [ 'directories' => [__DIR__ . '/schema'], 'parser_options' => [], ], 'cache' => [ 'enabled' => true, 'directory' => __DIR__ . '/cache', ], ]); // Create schema factory $schemaFactory = new GeneratedSchemaFactory($schemaConfig); $schema = $schemaFactory->createSchema();

Framework Integration

Slim 4

use Slim\Factory\AppFactory; $app = AppFactory::create(); $app->add($middlewareFactory->createMiddleware());

Mezzio

use Mezzio\Application; $app = new Application(); $app->pipe($middlewareFactory->createMiddleware());

Laravel

use Illuminate\Support\ServiceProvider; class GraphQLServiceProvider extends ServiceProvider { public function boot() { $middleware = $this->app->make(GraphQLMiddlewareFactory::class) ->createMiddleware(); $this->app['router']->middleware('graphql', $middleware); } }

Request Preprocessing

You can add authentication/authorization by implementing the RequestPreprocessorInterface:

use GraphQL\Middleware\RequestPreprocessorInterface; class AuthPreprocessor implements RequestPreprocessorInterface { public function process(ServerRequestInterface $request): ServerRequestInterface { $token = $request->getHeaderLine('Authorization'); if (!$this->isValidToken($token)) { throw new UnauthorizedException('Invalid token'); } return $request; } } // Add to middleware factory $middlewareFactory = new GraphQLMiddlewareFactory( serverConfig: $serverConfig, responseFactory: $psr17Factory, streamFactory: $psr17Factory, requestPreprocessor: new AuthPreprocessor() );

Development

Code Quality

The project uses PHP_CodeSniffer for coding standards and PHPStan for static analysis.

To check coding standards:

composer cs-check

To automatically fix coding standards:

composer cs-fix

To run static analysis:

composer stan

To run all checks (coding standards, static analysis, and tests):

composer check

Testing

To run the test suite:

composer test

Examples

Check the examples/ directory for complete working examples with different frameworks:

• examples/slim/ - Slim 4 integration
• examples/mezzio/ - Mezzio integration
• examples/laravel/ - Laravel integration

License

MIT License. See LICENSE file for details.

==========================

To use the middleware in Laminas Mezzio, configure the factories

in config/autoload/dependencies.global.php

return [ 'dependencies' => [ 'factories' => [ \GraphQL\Server\StandardServer::class => \Xaddax\GraphQL\Factory\StandardServerFactory::class, \GraphQL\Middleware\GraphQLMiddleware::class => \Xaddax\GraphQL\Factory\GraphQLMiddlewareFactory::class, ], ], ];

Add configuration in config/autoload/graphql.global.php

return [ 'graphQL' => [ 'middleware' => [ 'allowedHeaders' => [ 'application/graphql', 'application/json', ], ], 'schema' => \Path\To\Schema::class, // optional, defaults to webonyx Schema 'schemaConfig' => [], // optional, if not configured expected in Schema class constructor 'server' => \Path\To\Server::class, // not yet implemented, defaults to webonyx StandardServer 'serverConfig' => [ 'context' => \GraphQL\Context\TokenContext::class 'schema' => \Path\To\Your\Schema::class, ], ], ];

see the WebOnyx Server Configuration Documentation for the full options for the server config.

You'll need to set up the route. In config/routes.php

return function (Application $app, MiddlewareFactory $factory, ContainerInterface $container) : void { $app->post('/graphql', \GraphQL\Middleware\GraphQLMiddleware::class, 'graphql'); };

Schema Definition Language

You can also use a Schema Definition Language as discussed in the webonyx documentation.

In config/autoload/graphql.global.php change the schema in the serverConfig to generatedSchema

return [ 'graphQL' => [ 'serverConfig' => [ 'schema' => 'generatedSchema', ], ], ];

Then inside of the graphQL config add the generatedSchema configuration

return [ 'graphQL' => [ 'generatedSchema' => [ 'parserOptions' => [ 'experimentalFragmentVariables' => true, // to parse fragments 'noLocation' => false, // default, set true for development ], 'cache' => [ 'alwaysEnabled' => false, // default, set to true to cache when the system cache is not enabled 'directoryChangeFilename' => 'directory-change-cache.php', // default 'schemaCacheFilename' => 'schema-cache.php', // default  ], 'schemaDirectories' => [ '/full/path/to/schema-directory-1', '/full/path/to/schema-directory-2', ], ], ], ];

See the documentation for parserOptions

The cached data is stored in data/cache/graphql.