Laragraph developer guide

Laragraph is a code-first GraphQL server for Laravel: your types, queries and mutations are plain PHP classes, and everything else — validation, authorization, pagination, N+1 batching, subscriptions, caching — uses the Laravel features you already know.

This guide explains every feature, why it exists and how to use it safely. Almost every code sample comes from the example application, whose test suite runs against this repository — so the samples are known to work.

Contents

Start here

1. Getting started — install, your first type, query and mutation, how requests flow, and scaffolding a type/queries/mutations (with relations and enum casts) from an Eloquent model
2. Types — object, input, enum (including native PHP enums), interface and union types, scalars, and how types are registered
3. Queries & mutations — fields, arguments, resolvers, the context, validation (including reusing an existing FormRequest), errors, deprecation

Building a real API

4. Authentication & authorization — guards, authorize(), policies, field-level privacy
5. Relations & DataLoaders — solving N+1 with batchRelation() and custom loaders (generate one with laragraph:make:loader)
6. Pagination — Relay cursor connections, simple pagination, and Node re-fetching
7. Subscriptions — real-time updates over Laravel Broadcasting, or plain HTTP SSE
8. The HTTP API — GraphQL over HTTP, file uploads, batching, persisted queries, error codes
9. Multiple schemas — separate public and admin APIs

Running it in production

10. Security — defaults, limits, and a hardening checklist
11. Performance & caching — response cache, discovery cache, Octane
12. Observability — events, response extensions, tracing, logging
13. Testing — testing your GraphQL API with PHPUnit, shippable test helpers, and a first-party PHPStan rule for unregistered type names
14. Deployment — artisan commands, CI schema-diff gate, queues, broadcasting, checklists

Reference

15. Configuration reference — every option in config/laragraph.php
16. Upgrading — behaviour changes between releases
17. Error handling & localization — GraphQLException, error codes, and translating messages per request

Conventions used in this guide

• Laragraph::type('User') is the facade Ayimdomnic\Laragraph\Facades\Laragraph; app('laragraph')->type('User') is equivalent.
• Type in field definitions is webonyx's GraphQL\Type\Definition\Type. Laragraph's own base class for object types is also called Type (Ayimdomnic\Laragraph\Support\Type), so type classes usually import webonyx's as GType.
• "The example" means the application in example/.