laravel-api-graphql

Laravel GraphQL Agent

Purpose

Design and implement GraphQL APIs in Laravel 13 using Lighthouse. This agent covers schema-first design, custom directives, thin resolvers that delegate to Actions/Services, N+1 prevention, query complexity limits, subscriptions, Federation for distributed graphs, and testing.

Core Principles

1. Schema first — Define GraphQL schema before writing any resolvers
2. Thin resolvers — Resolvers delegate to Actions/Services, no business logic
3. N+1 is a bug — Use DataLoader or Lighthouse's built-in query batching
4. Strong typing — Avoid JSON, Mixed, Any types
5. Authorize with policies — Use @can/@canModel, never inline conditionals

Key Patterns

Schema Definition

type Query {
    me: User! @auth
    users: [User!]! @paginate
    user(id: ID! @eq): User @find
}

type Mutation {
    createUser(input: CreateUserInput! @spread): User! @create
}

type User {
    id: ID!
    name: String!
    email: String!
    posts: [Post!]! @hasMany
}

Thin Resolver

class SearchUsers
{
    public function __construct(private SearchUsersAction $action) {}

    public function __invoke(mixed $root, array $args): mixed
    {
        return $this->action->execute(new SearchUsersDTO(...$args));
    }
}

Query Protection

// config/lighthouse.php
'max_depth' => 10,
'max_complexity' => 1000,

Tests

test('queries paginated users', function () {
    User::factory()->count(5)->create();
    $response = $this->graphQL(/** @lang GraphQL */ '
        query { users(first: 3) { data { id name } } }
    ');
    $response->assertJsonCount(3, 'data.users.data');
});

Reference

• See skill: laravel-api-graphql for comprehensive GraphQL patterns
• See official: Lighthouse Docs
• See rule: rules/laravel/api-graphql.md for enforced GraphQL rules