MonkeysLegion-GraphQL

Code-first GraphQL server for the MonkeysLegion framework — PHP 8.4 attributes, PSR-15, DataLoader, subscriptions, and security out of the box.

Requirements

• PHP 8.4+
• webonyx/graphql-php ^15.30

Installation

composer require monkeyscloud/monkeyslegion-graphql

The GraphQLProvider is auto-registered via composer.json extra.

Quick Start

1. Define a Type

use MonkeysLegion\GraphQL\Attribute\{Type, Field};
#[Type(description: 'A user')]
final class UserType
{
    #[Field]
    public function id(User $root): int
    {
        return $root->id;
    }
#[Field]
public function name(User $root): string
{
    return $root->name;
}

#[Field(description: 'Email address')]
public function email(User $root): string
{
    return $root->email;
}

}

2. Define a Query

use MonkeysLegion\GraphQL\Attribute\{Query, Arg};
use MonkeysLegion\GraphQL\Context\GraphQLContext;
#[Query(name: 'user', description: 'Get user by ID')]
final class GetUserQuery
{
    public function __construct(private UserRepository $users) {}
public function __invoke(
    mixed $root,
    #[Arg(description: 'User ID')] int $id,
    GraphQLContext $context,
): ?User {
    return $this->users->find($id);
}

}

3. Define a Mutation

use MonkeysLegion\GraphQL\Attribute\{Mutation, Arg};
#[Mutation(name: 'createUser', description: 'Create a new user')]
final class CreateUserMutation
{
    public function __construct(private UserRepository $users) {}
public function __invoke(
    mixed $root,
    #[Arg] string $name,
    #[Arg] string $email,
): User {
    return $this->users->create($name, $email);
}

}

4. Configure

# config/graphql.mlc
graphql:
  endpoint: /graphql
  scan:
    directories:
      - app/GraphQL
  security:
    max_depth: 10
    max_complexity: 200

Features

Attributes

Attribute	Target	Purpose
#[Type]	Class	GraphQL object type
#[Field]	Method/Property	Object type field
#[Query]	Class	Root query field
#[Mutation]	Class	Root mutation field
#[Subscription]	Class	Subscription field
#[Arg]	Parameter	Argument metadata
#[InputType]	Class	Input object type
#[Enum]	Backed enum	Enum type
#[InterfaceType]	Class/Interface	Interface type
#[UnionType]	Class	Union type
#[Middleware]	Class/Method	Per-field middleware

Custom Scalars

• DateTime — ISO 8601 serialization
• JSON — Arbitrary JSON passthrough
• Email — Email format validation
• URL — URL format validation
• Upload — Multipart file upload

Security

graphql:
  security:
    max_depth: 10          # Query depth limiting
    max_complexity: 200    # Field cost analysis
    introspection: false   # Disable introspection in production
    persisted_queries: true # APQ with SHA256
    rate_limit:
      enabled: true
      max_requests: 100
      window_seconds: 60

DataLoader (N+1 Prevention)

use MonkeysLegion\GraphQL\Loader\DataLoader;
final class UserLoader extends DataLoader
{
    public function __construct(private UserRepository $users) {}
protected function batchLoad(array $keys): array
{
    $users = $this->users->findByIds($keys);
    return array_map(
        fn(int $id) => $users[$id] ?? null,
        $keys,
    );
}

}

Relay Pagination

use MonkeysLegion\GraphQL\Type\ConnectionType;
// Automatically creates UserConnection, UserEdge, PageInfo types
$connectionType = ConnectionType::create('User', $userType);

Subscriptions

use MonkeysLegion\GraphQL\Attribute\Subscription;
#[Subscription(name: 'messageAdded', description: 'New message')]
final class MessageAddedSubscription
{
    public function __invoke(mixed $root): Message
    {
        return $root;
    }
}

Supports graphql-ws protocol with in-memory and Redis PubSub backends.

File Uploads

Follows the GraphQL multipart request spec:

#[Mutation(name: 'uploadFile')]
final class UploadFileMutation
{
    public function __invoke(
        mixed $root,
        #[Arg] UploadedFileInterface $file,
    ): string {
        $file->moveTo('/uploads/' . $file->getClientFilename());
        return $file->getClientFilename();
    }
}

CLI Commands

Command	Description
php ml graphql:schema:dump	Dump schema as SDL
php ml graphql:schema:validate	Validate schema
php ml graphql:cache:warm	Warm schema cache
php ml graphql:cache:clear	Clear schema cache
php ml graphql:introspect	Dump introspection JSON

Entity Integration

When monkeyslegion-entity is installed, you can auto-map your entities to GraphQL types without writing boilerplate type classes.

Entity Example

use MonkeysLegion\Entity\Attribute\Entity;
use MonkeysLegion\Entity\Attribute\Id;
use MonkeysLegion\Entity\Attribute\Column;
#[Entity(table: 'products')]
class Product
{
    #[Id]
    public int $id;
#[Column(type: 'varchar', length: 255)]
public string $name;

#[Column(type: 'text')]
public string $description;

#[Column(type: 'decimal')]
public float $price;

#[Column(type: 'boolean')]
public bool $active;

#[Column(type: 'datetime')]
public \DateTimeImmutable $createdAt;

}

Auto-Map Entities to GraphQL Types

use MonkeysLegion\GraphQL\Scanner\EntityTypeMapper;
$mapper = new EntityTypeMapper();
// Maps all typed properties → GraphQL fields automatically:
//   int    → Int!        float  → Float!
//   string → String!     bool   → Boolean!
//   DateTime* → DateTime!  (custom scalar)
//   ?string → String     (nullable)
$typeConfig = $mapper->map(Product::class);
// Returns: ['name' => 'Product', 'fields' => ['id' => ..., 'name' => ..., ...]]
// Map multiple entities at once
$types = $mapper->mapAll([Product::class, Category::class, Order::class]);

Auto-Generated CRUD Resolvers

Use EntityResolver to expose entities without manual resolver classes:

use MonkeysLegion\GraphQL\Resolver\EntityResolver;
use MonkeysLegion\GraphQL\Type\ConnectionType;
// Single entity by ID
//   query { product(id: 42) { name price } }
$findProduct = EntityResolver::findById(
    Product::class,
    ProductRepository::class, // optional — defaults to Product::class . 'Repository'
);
// List all entities
//   query { products { name price active } }
$listProducts = EntityResolver::findAll(Product::class);
// Relay-style pagination with cursors
//   query { products(first: 10, after: "Y3Vyc29yOjk=") {
//     edges { node { name } cursor }
//     pageInfo { hasNextPage endCursor }
//     totalCount
//   }}
$paginatedProducts = EntityResolver::connection(Product::class);

Full Example: Entity-Backed Schema

use MonkeysLegion\GraphQL\Attribute\{Type, Field, Query, Arg};
use MonkeysLegion\GraphQL\Context\GraphQLContext;
// 1. Define the GraphQL type wrapping the entity
#[Type(description: 'A product in the catalog')]
final class ProductType
{
    #[Field]
    public function id(Product $root): int { return $root->id; }
#[Field]
public function name(Product $root): string { return $root->name; }

#[Field]
public function price(Product $root): float { return $root->price; }

#[Field(description: 'Active in store?')]
public function active(Product $root): bool { return $root->active; }

#[Field(description: 'ISO 8601')]
public function createdAt(Product $root): string {
    return $root->createdAt->format('c');
}

}
// 2. Query resolver using the repository from DI
#[Query(name: 'product', description: 'Find product by ID')]
final class GetProductQuery
{
    public function __construct(private ProductRepository $products) {}
public function __invoke(
    mixed $root,
    #[Arg(description: 'Product ID')] int $id,
    GraphQLContext $context,
): ?Product {
    return $this->products->find($id);
}

}
// 3. List with filtering
#[Query(name: 'products', description: 'List products')]
final class ListProductsQuery
{
    public function __construct(private ProductRepository $products) {}
public function __invoke(
    mixed $root,
    #[Arg(nullable: true)] ?bool $active,
    #[Arg(nullable: true, defaultValue: 20)] int $limit,
): array {
    if ($active !== null) {
        return $this->products->findByActive($active, $limit);
    }
    return $this->products->findAll($limit);
}

}

Route Registration

GraphQLProvider automatically registers routes with monkeyslegion-router when the application boots.

Default Routes

Method	Path	Handler	Description
POST	/graphql	GraphQLMiddleware	Queries & mutations
GET	/graphql	GraphQLMiddleware	Simple GET queries
GET	/graphiql	GraphiQLMiddleware	Interactive IDE (dev)

Configuration

# config/graphql.mlc
graphql:
  endpoint: /graphql            # Change the endpoint path
  graphiql_enabled: true        # Disable GraphiQL in production
  graphiql_endpoint: /graphiql  # Custom GraphiQL path
  debug: false                  # Enable for detailed error traces
  scan_dirs:
    - app/GraphQL               # Where to find Type/Query/Mutation classes
  scan_namespace: App\GraphQL   # PSR-4 namespace for scanned classes
  security:
    max_depth: 10
    max_complexity: 200
    introspection: true         # Disable in production
    persisted_queries: false
    rate_limit:
      max_requests: 100
      window_seconds: 60
  cache:
    enabled: false
    ttl: 3600                   # Schema cache TTL in seconds
  subscriptions:
    enabled: false
    driver: memory              # 'memory' or 'redis'
    host: 0.0.0.0
    port: 6001
    redis_dsn: redis://127.0.0.1:6379

How Route Registration Works

The GraphQLProvider::register() method is called automatically during application bootstrap (via the monkeyslegion extra in composer.json). Here's what happens:

// This happens automatically — no manual setup needed.
// The provider:
//   1. Reads config/graphql.mlc
//   2. Registers all GraphQL services in the DI container
//   3. Registers routes with MonkeysLegion\Router\Router
// Routes are registered as closures that delegate to PSR-15 middleware:
$router->post('/graphql', $graphqlHandler, 'graphql');
$router->get('/graphql', $graphqlHandler, 'graphql.get');
$router->get('/graphiql', $graphiqlHandler, 'graphiql'); // if enabled

Custom Route Middleware

Stack your own middleware (auth, CORS, rate-limiting) alongside GraphQL:

use MonkeysLegion\GraphQL\Attribute\Middleware;
// Per-resolver middleware
#[Middleware('App\Middleware\AuthMiddleware')]
#[Middleware('App\Middleware\RateLimitMiddleware')]
#[Query(name: 'adminUsers')]
final class AdminUsersQuery
{
    public function __invoke(mixed $root, GraphQLContext $context): array
    {
        // Only reached if auth + rate-limit pass
        return $context->container->get(UserRepository::class)->findAdmins();
    }
}

Testing the Endpoint

# Simple query
curl -X POST http://localhost:8080/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query": "{ product(id: 1) { name price } }"}'
Mutation
curl -X POST http://localhost:8080/graphql 
  -H 'Content-Type: application/json' 
  -d '{"query": "mutation { createProduct(name: "Widget", price: 9.99) { id name } }"}'
GET request (simple queries only)
curl 'http://localhost:8080/graphql?query=\{products\{name\}\}'
Open GraphiQL IDE in browser
open http://localhost:8080/graphiql

Facade

use MonkeysLegion\GraphQL\GraphQL;
// Execute a query programmatically
$result = GraphQL::execute('{ user(id: 1) { name } }');
// Publish a subscription event
GraphQL::publish('messageAdded', $message);
// Get the built schema
$schema = GraphQL::schema();

License

MIT — see LICENSE for details.