Download the PHP package hmennen90/laravel-graphql without Composer

laravel-graphql

A hand-written GraphQL engine with first-class Laravel integration — no dependency on webonyx/graphql-php. Define your schema code-first (PHP), schema-first (SDL), attribute-driven, or mix all three; they compile to one internal schema.

Status: in active development. APIs may change before the first stable release.

Key differentiator — single source of truth

Unlike SDL-first stacks, you do not implement a type twice. There is no SDL type mirroring your Eloquent model plus a separate type/transformer class, and no directive DSL to keep in sync. Declare a type once; resolvers are plain PHP callables that read your models directly.

Features

• Own lexer, parser, AST, type system, validator and executor (spec-driven).
• Hybrid schema: code-first, SDL, and PHP attributes — one internal schema.
• Built-in scalars (Int, Float, String, Boolean, ID) + custom scalars.
• Objects, interfaces, unions, enums, input objects, lists, non-null.
• Comprehensive validation, introspection (GraphiQL/Apollo tooling), @oneOf, @specifiedBy.
• Custom directives (runtime middleware and build-time SDL), SDL type extensions.
• Eloquent directive layer (@all, @find, @paginate, @hasMany, @whereConditions, @orderBy, @create/@update/@delete, @search, …) — available as SDL directives and equivalent PHP attributes (#[All], #[Paginate]).
• Argument sanitisers & validation: @trim, @hash, @globalId, @rules, @validator.
• DataLoader (N+1 batching), query depth/complexity limits.
• Laravel: HTTP endpoint, batching, middleware/auth, error masking, GraphiQL, file uploads, Automatic Persisted Queries, @cacheControl HTTP caching, Relay pagination, subscriptions (broadcasting, graphql-ws + SSE), Apollo Federation.
• PHP 8.4, PHPStan level 10, tested with orchestra/testbench + a GraphQL spec conformance suite (language, validation, execution, introspection), parser fuzzing and Infection mutation testing (engine core: 100% mutation coverage, ~79% MSI).

Requirements

• PHP ^8.4
• Laravel 11, 12 or 13 (for the Laravel integration; the engine itself is framework-agnostic)

Installation

Publish the config (and optionally a starter schema):

Quick start (Laravel)

Create a schema provider:

Register it in config/graphql.php:

Query the endpoint:

Defining a schema

Code-first

Recursive/cyclic types are fine — pass a closure for lazily-resolved fields:

Schema-first (SDL)

Fields without a resolver fall back to reading array keys, object properties or getters.

Attribute-driven

SDL type extensions

Eloquent directives (CRUD without resolvers)

Build a full CRUD API over Eloquent declaratively — the model stays the single source of truth, and directives derive queries, columns and relations from it.

Everything is also available as PHP attributes that dispatch to the exact same implementations — pick SDL or code-first per taste, with no duplicated logic:

Reading (@all/@find/@first/@paginate), relations (@hasMany/@hasOne/@belongsTo/@belongsToMany/@morph*/@count), filtering & sorting (@whereConditions/@orderBy), mutations incl. nested (@create/@update/@delete/@upsert), auth/utility (@guard/@inject/@field/@rename) and Laravel Scout (@search) are all supported. See Eloquent directives for the full reference.

Apollo Federation

Expose any schema as a federated subgraph:

This adds _service { sdl }, _entities(representations:) and the _Any/_Service/ _Entity types, wiring one reference resolver per entity type. See Apollo Federation.

Generating types from your Laravel app

The strongest form of "single source of truth": derive GraphQL types from the artifacts you already maintain — Eloquent models, FormRequest rules and JSON responses — instead of re-declaring their shape.

Compose the generated types into a schema like any hand-built type:

Mapping notes: model casts and rule tokens map to the built-in scalars; array/json casts and array rules use a bundled JSON scalar. Nested resource arrays become nested object types. Generators produce a starting point you can refine — add relations, hide fields, or wrap the returned types as needed.

Executing standalone (without Laravel)

The engine has no framework dependency:

Or validate first:

Laravel integration

Configuration

config/graphql.php controls the endpoint, GraphiQL, schema source, batching, error handling, security limits, persisted queries, cache-control and subscriptions.

Artisan commands

The GraphQL facade

Authorization

Inside a resolver, use the request Context:

Or declaratively in SDL with the @can directive:

Argument validation

Use Laravel's validator inside a resolver; a thrown ValidationException surfaces under errors[].extensions.validation:

Or declaratively in SDL with the built-in directives — @rules validates a single argument, @validator binds a dedicated validator class, and the sanitisers run before the resolver:

• @rules(apply: [...]) — validate one argument with Laravel rules.
• @validator(class:) — validate all arguments via a class exposing rules().
• @trim — strip surrounding whitespace; @hash — bcrypt a value; @globalId — decode a Relay global id down to its raw key.

See Validation & argument sanitisers for the full reference.

Error masking

With graphql.debug = false, internal exception messages are masked to "Internal server error". Client-safe exceptions (authorization, authentication, validation) pass through and are categorised under extensions.category.

File uploads

Add the Upload scalar and send a GraphQL multipart request:

Uploaded files arrive as Illuminate\Http\UploadedFile instances.

Automatic Persisted Queries (APQ)

Clients send extensions.persistedQuery.sha256Hash; the first request registers the query, later requests may send the hash alone.

HTTP caching (@cacheControl)

The endpoint emits a Cache-Control header from the minimum maxAge of the selected fields. Combined with APQ (GET + hash), this enables CDN/HTTP caching.

Subscriptions

Enable and broadcast events:

Clients subscribe via Laravel Echo (broadcasting) or a graphql-ws client. To run the bundled graphql-ws server (requires the Swoole extension):

Performance

DataLoader (N+1 batching)

All companies requested during one query are fetched in a single batch call.

Query limits

Benchmarks

A dependency-free harness measures each phase (parse/build/validate/execute), list throughput and DataLoader batching:

Indicative results on an Apple Silicon laptop, PHP 8.4 (no JIT) — median over many iterations. Numbers are machine-specific; the shape (per-phase cost, scaling) is what matters:

Parse, validate and small executions run in microseconds; list execution scales linearly (~3.8 µs/object) after the executor completes synchronous fields inline. In an engine-to-engine comparison this beats webonyx/graphql-php (Lighthouse's engine) across every scenario, and end-to-end (Laravel + Eloquent) it resolves ~1.5× faster than Lighthouse. See Benchmarks.

Custom directives

Runtime (query) directive — wrap field resolution:

Build-time SDL directives implement SchemaDirective and are passed to SchemaBuilder::fromSdl(..., schemaDirectives: [...]) (see @can/@cacheControl).

Relay pagination

Introspection & GraphiQL

Full introspection is supported. With graphql.graphiql.enabled = true, an in-browser IDE is served at /graphiql.

Testing

Contributing

Contributions are welcome — see CONTRIBUTING.md. Commits follow Conventional Commits; releases are cut with semantic-release. Please also read the Code of Conduct.

Security

Please report security issues privately — see SECURITY.md.

Changelog

See CHANGELOG.md (generated by semantic-release).

Comparison

A full, per-package feature comparison (vs. Lighthouse, rebing/graphql-laravel, webonyx/graphql-php) is in the documentation.

Migrating from Lighthouse

Not a drop-in replacement, but a realistic migration: the CRUD, relation, filter/sort (incl. single-field @eq/@like/@scope/@limit…), soft-delete and auth directive names and semantics were kept compatible, and convention-resolved query/mutation classes carry over (graphql.namespaces). Run php artisan graphql:lint to get a precise list of anything unsupported (e.g. @builder, @with, subscriptions), and use the MakesGraphQLRequests test trait so existing feature tests keep working. See the full migration guide.

License

MIT — see LICENSE.