.ai

Imported from gencau/test-practices-agent-configurations (dataset/repos/nuwave§lighthouse/.ai/AGENTS.md). Install upstream with npx skills add gencau/test-practices-agent-configurations --skill .ai. Copyright stays with the author.

AGENTS.md

This file provides guidance to coding agents when working with code in this repository.

Project Overview

Lighthouse is a GraphQL framework for Laravel that uses a schema-first approach with directives. It integrates webonyx/graphql-php with Laravel's ecosystem.

Development Commands

The project uses Docker + Make for a reproducible development environment.

make setup          # Initial setup: build containers, install dependencies, generate agent config
make it             # Run all checks before committing (fix, stan, test)
make fix            # Auto-format code (rector, php-cs-fixer, prettier)
make stan           # Static analysis with PHPStan
make test           # Run PHPUnit tests
make bench          # Run PHPBench benchmarks

Running a Single Test

docker compose exec php vendor/bin/phpunit --filter=TestClassName
docker compose exec php vendor/bin/phpunit --filter=testMethodName
docker compose exec php vendor/bin/phpunit tests/Unit/Path/To/TestFile.php

Architecture

Entry Points

• src/LighthouseServiceProvider.php - Main service provider, registers singletons and bindings
• src/GraphQL.php - Main entrypoint to GraphQL execution (@api marked)
• src/Http/routes.php - GraphQL endpoint routing

Schema Processing Pipeline

1. Schema Source (src/Schema/Source/) - SchemaStitcher loads and combines .graphql files
2. AST Building (src/Schema/AST/) - ASTBuilder parses schema into AST nodes
3. Schema Building (src/Schema/SchemaBuilder.php) - Builds executable GraphQL schema
4. Type Registry (src/Schema/TypeRegistry.php) - Manages GraphQL types

Directive System

Directives are the core extension mechanism. Located in src/Schema/Directives/.

• BaseDirective - Abstract base class for all directives, provides common utilities
• Directive interfaces in src/Support/Contracts/ define capabilities:
  • FieldResolver - Resolves field values
  • FieldMiddleware - Wraps field resolution
  • ArgTransformerDirective - Transforms argument values
  • ArgBuilderDirective - Modifies query builder
  • TypeManipulator, FieldManipulator, ArgManipulator - Schema manipulation

Directives are named by convention: FooDirective maps to @foo in GraphQL schema.

Service Providers

Multiple service providers for optional features (auto-discovered via composer.json):

• AuthServiceProvider - Authentication directives (@auth, @can, @guard)
• CacheServiceProvider - Query result caching (@cache)
• PaginationServiceProvider - Pagination types and directives
• ValidationServiceProvider - Input validation (@rules)
• SoftDeletesServiceProvider, GlobalIdServiceProvider, OrderByServiceProvider

Testing Infrastructure

• tests/TestCase.php - Base test class using Orchestra Testbench
• tests/DBTestCase.php - Tests requiring database (MySQL)
• MakesGraphQLRequests trait - $this->graphQL($query) helper for testing
• MocksResolvers trait - Mock field resolvers
• UsesTestSchema trait - Set schema via $this->schema = '...'

Tests use Tests\Utils\ namespace for test fixtures (Models, Queries, Mutations, etc.).

Test data setup

Use relations over direct access to foreign keys.

$user = factory(User::class)->create();

// Right
$post = factory(Post::class)->make();
$post->user()->associate($user);
$post->save();

// Wrong
$post = factory(Post::class)->create([
    'user_id' => $user->id,
]);

Use properties over arrays to fill fields.

// Right
$user = new User();
$user->name = 'Sepp';
$user->save();

// Wrong
$user = User::create([
    'name' => 'Sepp',
]);

GraphQL string style in tests

• Always annotate GraphQL literals with /** @lang GraphQL */.
• Default to nowdoc: <<<'GRAPHQL'.
• Use heredoc: <<<GRAPHQL only if interpolation is required.
• Avoid quoted multiline GraphQL strings.
• Preserve intentional indentation/whitespace in schema and assertion-sensitive tests.

Code Style

• PHPStan level 8
• php-cs-fixer with mll-lab/php-cs-fixer-config (risky rules)
• protected over private for extensibility
• Never use final in src/, always in tests/
• Full namespace in PHPDoc (@var \Full\Namespace\Class), imports in code
• Code elements with @api have stability guarantees between major versions
• Use Semantic Line Breaks for prose in markdown and multiline comments
• Default to one sentence per line and avoid comma/clause-only line breaks

Pull Requests

Follow the PR template:

• Link related issues
• Add or update tests
• Document user-facing changes in /docs
• Update CHANGELOG.md for non-docs-only changes

Changelog

Add entries to the ## Unreleased section in CHANGELOG.md for non-docs-only changes. Use categories: Added, Changed, Deprecated, Removed, Fixed, Security. End each entry with a full PR URL: https://github.com/nuwave/lighthouse/pull/<number>.

See CONTRIBUTING.md for full guidelines.