Download the PHP package ayimdomnic/laragraph without Composer

Laragraph

A modern, feature-rich GraphQL package for Laravel.

Laragraph gives Laravel developers a clean, expressive, code-first API for building GraphQL services — powered by webonyx/graphql-php.

📖 Read the developer guide: a step-by-step explanation of every feature, from your first query to production. 🧪 Explore the example app: a complete API that uses every feature, with a test for each one.

Table of Contents

• Features
• Requirements
• Why Laragraph?
• Installation
• Quick Start
• Native PHP Enums
• GraphiQL
• Artisan Generators
• Deploying
• Pagination
• N+1-Safe Eloquent Relations
• Authorization
• Validation
• Error Handling & Localization
• Built-in Scalars
• Multiple Schemas
• Security
• GraphQL over HTTP
• Response Cache
• Persisted Queries
• Batched Queries
• File Uploads
• Facade
• Subscriptions
• Tracing
• Development
• Contributing
• License

Features

Requirements

• PHP 8.2 – 8.5
• Laravel 10 / 11 / 12 / 13 (Laravel 13 requires PHP 8.3+)

Every combination Laravel itself supports is tested in CI.

Why Laragraph?

Laragraph is code-first: types, queries and mutations are plain PHP classes, so your IDE, refactoring tools and PHPStan understand your whole API. On top of webonyx/graphql-php it adds the parts a Laravel team otherwise builds by hand:

• Laravel-native everything — validation rules, policies and guards, Broadcasting for subscriptions, cache stores, php artisan about, optimize, and generators.
• Performance by default — N+1-safe Eloquent relation batching through the model's own eager loading, a per-user response cache, persisted queries and a cached discovery manifest.
• Secure by default — depth/complexity/alias limits, no mutations over GET, trusted-documents mode, and per-user cache partitioning so one user's data is never served to another.
• Modern PHP — native enums, readonly value objects, strict types throughout and no dynamic properties (deprecated since PHP 8.2).

Installation

Laravel auto-discovers the package. Publish the config:

Quick Start

1. Create a Type

2. Create a Query

3. Create a Mutation

4. Register in config/laragraph.php

5. Make requests

Native PHP Enums

Register a backed or pure enum directly — no wrapper class needed:

Resolvers return enum cases and receive cases for enum arguments. #[Description] and #[Deprecated] attributes on the enum and its cases are exposed through introspection. An EnumType subclass may also simply return UserStatus::cases(); from values().

Enums (and input, interface, union and scalar types) placed in app/GraphQL/Types are auto-discovered — including subdirectories such as app/GraphQL/Types/Billing/.

GraphiQL

Built-in browser IDE at /graphql/graphiql. By default ('enabled' => null) it is only served while app.debug is on — never in production.

Artisan Generators

Scaffolded code is deny-by-default: every generated query and mutation calls Gate::allows() for the matching policy ability (viewAny, view, create, update, delete), so nothing is reachable until you write a policy, and attributes in the model's $hidden list (passwords, tokens) are never added to the generated type.

Deploying

Like Laravel's event and route caches, a cached manifest is not refreshed automatically — rerun laragraph:cache (or optimize) when you add GraphQL classes.

Pagination

Relay Cursor Pagination

Pass endCursor as after to fetch the next page, or startCursor as before with last to walk backwards; the page size may change between requests. Page sizes are capped by laragraph.pagination.max_per_page (default 100; null removes the cap). Eloquent builders, query builders and relations are paged with exact offsets; any other object with Laravel's paginate() signature supports page-aligned windows.

Simple Offset Pagination

Node re-fetching

A generic node(id: ID!): Node root field for Relay clients — register Ayimdomnic\Laragraph\Relay\NodeQuery, then override resolveNode() on any type implementing Node. See Pagination → Relay Node re-fetching.

N+1-Safe Eloquent Relations

Every GraphQL request gets a fresh DataLoaderRegistry attached to $context. For hand-written batch loaders, extend BatchResolver:

For HTTP requests $context is an Ayimdomnic\Laragraph\Http\GraphQLContext — a regular Illuminate\Http\Request (input, headers, user(), session all work) with declared slots for Laragraph's per-request state, so no dynamic properties are ever added to Laravel's request.

For a plain Eloquent relation, skip the hand-written loader entirely — Type::batchRelation() batches it through the relation's own eager-loading machinery (the same code path Model::with() uses), so it works for belongsTo, hasOne, hasMany, belongsToMany, and morph relations alike:

Regardless of how many Post parents are in the result set, comments resolves in one query per request instead of one query per post. The relation is loaded onto the parent models your resolver already returned, so relations you eager-loaded yourself (Post::with('comments')) cost no query at all, and parents hidden by global scopes still resolve.

Authorization

false → AuthorizationException → extensions.category = 'authorization'.

Or delegate to a Laravel policy — return the policy class or the model it guards:

Policies registered with the Gate go through it (so Gate::before() hooks apply); other policy classes are called directly, honouring their own before(). Guests are denied unless the policy method accepts a nullable user.

Validation

Errors appear in extensions.validation:

Error Handling & Localization

Throw a GraphQLException for domain/business errors — it's always client-safe, comes with a machine-readable extensions.code, and its message is resolved through Laravel's translator:

Generate one with php artisan laragraph:make:exception OutOfStockException. Any exception implementing graphql-php's ClientAware + ProvidesExtensions (which GraphQLException, ValidationException and AuthorizationException all do) gets picked up by formatError() automatically — no instanceof chain to maintain.

Localization is opt-in and off by default. Turn it on to translate messages per request based on the Accept-Language header, restricted to an allow-list:

Publish and translate lang/en/errors.php (php artisan vendor:publish --tag=laragraph-lang), and add your app's own lang/{locale}/errors.php for messages passed to GraphQLException. See Error Handling & Localization for the full guide, including the supported_locales allow-list security note.

Built-in Scalars

Date accepts YYYY-MM-DD (parsed as midnight). DateTime accepts ISO-8601 with or without fractional seconds (2024-01-15T09:30:00.123Z, as JavaScript's toISOString() produces), the SQL format 2024-01-15 09:30:00, and plain dates. Impossible values such as 2024-02-31 are rejected rather than rolled over.

Multiple Schemas

Endpoints: POST /graphql and POST /graphql/admin.

Security

Secure by default — these are the shipped values:

Set a limit to null to remove it, or disable_introspection to true/false to force it.

Each named schema only contains the types registered for it (globally or under its own types key); an admin-only type is never visible through another schema's introspection.

See also trusted documents.

GraphQL over HTTP

Laragraph follows the GraphQL-over-HTTP specification:

• GET executes queries only; mutations over GET receive 405 Method Not Allowed (they would otherwise be exploitable via CSRF).
• Clients sending Accept: application/graphql-response+json get that media type, with a 4xx status when a request fails before execution (parse/validation errors). Plain application/json clients keep the traditional always-200 behaviour.
• Request bodies may be application/json, application/graphql, form-encoded or multipart.
• Malformed requests (a non-string query, variables that are not an object, unparseable JSON, a non-object batch entry) get 400 with extensions.code: BAD_REQUEST; an unknown schema in the URL gets 404 with SCHEMA_NOT_FOUND.
• Requests rejected before execution carry a machine-readable extensions.code (BAD_REQUEST, SCHEMA_NOT_FOUND, METHOD_NOT_ALLOWED, PERSISTED_QUERY_NOT_FOUND, PERSISTED_QUERY_REQUIRED, …).

Response Cache

Only query operations are cached — the operation type is read from the parsed document, so comments or operationName cannot smuggle a mutation into the cache. With the default user scope, entries are partitioned per authenticated user (guests share one partition). Invalidate everything with ResponseCache::flush().

Persisted Queries

• Automatic Persisted Queries — compatible with Apollo Client's persisted-queries link: the client sends a SHA-256 hash, and on PersistedQueryNotFound retries with the full query, which is then stored (hashes are verified). Works over GET too.
• Trusted documents — with 'only' => true, only query text already stored under its hash is executed. Pre-populate the store at deploy time (or use the array store) to restrict your API to the operations your own clients ship.

Batched Queries

File Uploads

Follows the GraphQL multipart request spec.

Facade

Subscriptions

webonyx/graphql-php has no subscription transport of its own, so Laragraph provides one on top of Laravel Broadcasting: the initial subscription request registers a subscriber and returns a channel; your app code later calls Laragraph::broadcast() to push a live update to every subscriber on that channel.

Trigger an update from anywhere — typically at the end of a mutation:

Client flow:

1. POST the subscription operation like any other query:

   The response carries no data yet — instead:

2. Listen for updates on that subscriber's private channel with Laravel Echo:

Delivery uses whichever broadcast driver your app has configured (Reverb, Pusher, …) — Laragraph only decides the channel and payload shape.

Queued fan-out. Laragraph::broadcast() re-runs every subscriber's query before returning. Use Laragraph::broadcastLater('users', $user) to do that on the queue instead (subscriptions.queue.connection / subscriptions.queue.queue).

Unsubscribing. Clients cancel with DELETE /graphql/subscriptions/{subscriberId} (only the subscription's owner may; anything else answers 404), and server code can call Laragraph::unsubscribe($subscriberId). Subscriptions also expire after subscriptions.ttl.

Security. Each update is resolved as the subscriber: the subscriber's identity is stored when they subscribe, and Laragraph::broadcast() re-runs their query authenticated as them — never as whoever triggered the broadcast — so authorize(), policies and auth() behave exactly as on the original request. Laragraph also registers the private-channel rule for graphql-subscriber.{subscriberId}, admitting only the user who created the subscription (turn off with 'subscriptions' => ['authorize_channel' => false] to write your own in routes/channels.php). Because updates use private channels, subscribers must be authenticated to receive them. Set 'subscriptions' => ['driver' => 'log'] to write updates to the log instead, useful for local development without a broadcast server.

No broadcaster available? Set 'subscriptions' => ['driver' => 'sse'] and clients get updates over a plain HTTP Server-Sent Events connection instead — just a stock EventSource, no Echo, no Reverb/Pusher. Read the capacity trade-offs in Subscriptions → SSE transport before using it beyond a handful of subscribers: each open connection holds one worker for a bounded duration, unlike a dedicated WebSocket server.

Tracing

Enable per-field resolver timing in the Apollo Tracing format, understood out of the box by existing GraphQL tooling:

Every resolved field is recorded — root Query/Mutation/Subscription fields and nested Type fields alike. Leave this off in production unless you're actively debugging performance; it adds a small wrapping cost to every resolver call.

Set 'driver' => 'otel' instead to export real OpenTelemetry spans (a root span per operation, a child per resolver) via open-telemetry/api's global tracer provider — your app wires up its own OTel SDK/exporter. See Observability → The otel driver.

Development

See benchmarks/README.md for how the performance budgets and benchmarks work and how to check a change for regressions.

CI runs the suite on every supported PHP × Laravel combination (including --prefer-lowest), enforces 100% line coverage, and fails on any PHP deprecation.

Contributing

Contributions, issues, and feature requests are welcome! See CONTRIBUTING.md for the local dev loop and the quality gate every PR needs to pass, and CODE_OF_CONDUCT.md for community expectations. Found a security issue? See SECURITY.md instead of opening a public issue.

License

MIT © Odhiambo Dormnic