mathsgod/light-graphql

Simple graphql server

v1.3.0 2026-05-26 05:18 UTC

Requires

• php: ^8.3
• ecodev/graphql-upload: ^8.0
• laminas/laminas-diactoros: ^3.5
• league/container: ^5.2
• mathsgod/graphqlite-mixed-type: ^2.3
• symfony/cache: ^7.4
• thecodingmachine/graphqlite: ^8.0

Requires (Dev)

• phpunit/phpunit: ^12.0

MIT

• Raymond Chong

README

A lightweight GraphQL server library for PHP 8.3+, built on top of thecodingmachine/graphqlite.

Requirements

• PHP 8.3+

Installation

composer require mathsgod/light-graphql

Dependencies

Package	Purpose
thecodingmachine/graphqlite	GraphQL schema generation via PHP attributes
league/container	Dependency injection container
symfony/cache	Schema caching
ecodev/graphql-upload	File upload support (multipart/form-data)
laminas/laminas-diactoros	PSR-7 HTTP request/response

Usage

Define a Controller

Use #[Query] and #[Mutation] attributes from GraphQLite to define your GraphQL fields:

namespace Controllers;

use TheCodingMachine\GraphQLite\Annotations\Query;

class UserController
{
    #[Query]
    public function hello(): string
    {
        return 'world';
    }
}

Execute a Query Directly

require_once __DIR__ . '/vendor/autoload.php';

$server = new \Light\GraphQL\Server();
$server->getSchemaFactory()->addNamespace('Controllers');

$result = $server->executeQuery('{ hello }');
print_r($result->toArray());

Handle a PSR-7 Request

Server implements Psr\Http\Server\RequestHandlerInterface and supports both application/json and multipart/form-data (file uploads):

$server = new \Light\GraphQL\Server();
$server->getSchemaFactory()->addNamespace('Controllers');

// $request is a PSR-7 ServerRequestInterface
$response = $server->handle($request);

Constructor Options

$server = new \Light\GraphQL\Server(
    defaultLifetime: 15,   // Schema cache TTL in seconds (default: 15)
    debug: false,          // Enable debug mode (default: false)
    container: null        // Custom PSR-11 container (default: League\Container)
);

Debug Mode

When debug: true, error responses include the exception message and stack trace in the extensions field:

{
  "errors": [
    {
      "message": "Something went wrong",
      "extensions": {
        "trace": [...]
      }
    }
  ]
}

Error Responses

All responses follow the standard GraphQL error format and always return HTTP 200:

{
  "errors": [
    { "message": "..." }
  ]
}

API

Method	Description
getSchemaFactory(): SchemaFactory	Returns the GraphQLite SchemaFactory for adding namespaces
getContainer(): ContainerInterface	Returns the DI container
getCache(): CacheInterface	Returns the PSR-16 cache instance
executeQuery(?string $query, array $variables, ?string $operationName): ExecutionResult	Execute a GraphQL query directly
handle(ServerRequestInterface $request): ResponseInterface	Handle a PSR-7 HTTP request
executeGraphQLRequest(ServerRequestInterface $request): ResponseInterface	Process a pre-parsed PSR-7 request (used internally by handle())