optigov / eloquent-graphql
This package provides automatic creation of GraphQL types and fields from Eloquent models.
Requires
- php: ^8.2
- laravel/framework: ^11.4|^12.0|^13.0
- webonyx/graphql-php: ^v15.0
Requires (Dev)
- laravel/pint: ^1.13
- phpunit/phpunit: ^9.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-master
- v5.0.1
- v5.0.0
- v4.0.1
- v4.0.0
- v3.3.1
- v3.3.0
- v3.2.2
- v3.2.1
- v3.2.0
- v3.1.9
- v3.1.8
- v3.1.7
- v3.1.6
- v3.1.5
- v3.1.4
- v3.1.3
- v3.1.2
- v3.1.1
- v3.1.0
- v3.0.1
- v3.0.0
- v2.4.10
- v2.4.9
- v2.4.8
- v2.4.7
- v2.4.6
- v2.4.5
- v2.4.4
- v2.4.3
- v2.4.2
- v2.4.1
- v2.4.0
- v2.3.5
- v2.3.4
- v2.3.3
- v2.3.2
- v2.3.1
- v2.3.0
- v2.2.3
- v2.2.2
- v2.2.1
- v2.2.0
- v2.1.10
- v2.1.9
- v2.1.8
- v2.1.7
- v2.1.6
- v2.1.5
- v2.1.4
- v2.1.3
- v2.1.2
- v2.1.1
- v2.1.0
- v2.0.8
- v2.0.7
- v2.0.6
- v2.0.5
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.0
- v0.2.7
- v0.2.6
- v0.2.5
- v0.2.4
- v0.2.3
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.3
- v0.1.2
- v0.1.1
- v0.1.0
- dev-bugfix/relation-connectability
- dev-bugfix/filter-oracle
- dev-test/enum-coverage
- dev-bugfix/property-api-readonly
- dev-feature/duplicate
- dev-feature/relation-pre-fetching
This package is auto-updated.
Last update: 2026-11-13 14:31:59 UTC
README
This package automatically creates GraphQL types and fields with their resolvers for the webonyx/graphql-php library
from Eloquent models. The package
utilizes the PHP DocBlock annotations to determine the GraphQL types and fields.
It supports pagination, filtering and ordering on properties returning multiple models using a query builder
for optimal performance.
Installation
composer require optigov/eloquent-graphql
Usage
Annotate your Models
In order to make fields available in GraphQL, annotate your Models with the @property annotation.
/** * @property int $id * @property string $name * @property Author $author * @property-read $created_at * @property-read $updated_at */ class Book { // ... }
/** * @property int $id * @property string $first_name * @property string $last_name * @property Books[] $books * @property-read $created_at * @property-read $updated_at */ class Author { // ... }
Build your Schema
Build your Schema using the EloquentGraphQLService class.
use App\Models\Book; use App\Models\Author; use GraphQL\Type\Schema; use EloquentGraphQL\Services\EloquentGraphQLService; $graphQLService = new EloquentGraphQLService(); $schema = new Schema([ 'query' => $graphQLService->query() ->view(Book::class) ->view(Author::class) ->all(Book::class) ->all(Author::class) ->build(), 'mutation' => $graphQLService->mutation() ->create(Book::class) ->create(Author::class) ->update(Book::class) ->update(Author::class) ->delete(Book::class) ->delete(Author::class) ->build(), ]);
Go Further
Pagination
Use the @paginate annotation to paginate properties returning multiple models using a query builder - for example has
many relations.
/** * ... * @property Books[] $books @paginate * ... */ class Author { // ... }
Filtering and Ordering
Use the @filterable and @orderable annotations to enable filtering and ordering on properties returning multiple
models using a query builder - for example has many relations.
/** * ... * @property Books[] $books @paginate @filterable @orderable * ... */ class Author { // ... }
Authorization
Every model needs a Laravel policy implementing EloquentGraphQLPolicyContract. Models without such a policy are not
viewable. Besides the usual abilities, visibility() defines which models the user can view:
class AuthorPolicy implements EloquentGraphQLPolicyContract { public function visibility(?Authenticatable $user): Visibility { if ($user !== null) { return Visibility::all(); } return Visibility::where(fn (Builder $query) => $query->where($query->qualifyColumn('visible'), true)); } // ... }
Visibility::all(), Visibility::none() and Visibility::allIf(bool) need no database query. Non-Eloquent types may
only use those.
- Every query of the package (lists, counts, single entries, relations, filters and orders on relations, and the models
looked up by mutations) is restricted with
security()->constrain(). Hidden models are neither returned nor counted, and a hidden single entry or has-one relation resolves tonull. - Every field of a model checks
security()->canView()first. Models loaded throughconstrain()are known to be viewable, so this costs no query. Any other model, e.g. one returned by a custom resolver, is checked once against the visibility. Models created within the request are viewable.security()->canViewAs($model, $user)checks a model for another user, e.g. in a policy'sview(). - Models connected by mutations are restricted with
connectability(), which is usuallyvisibility(). It may allow more, e.g. freshly uploaded files that nobody can view yet. Connectable models are not remembered as viewable. A mutation fails as a whole if it would connect a model that is not connectable, or remove or replace one the user cannot view. Unchanged relations are kept as they are. - Ordering by a property requires the same permission as filtering by it (
filterProperty()).
Custom resolvers that act on a model should check it before doing so, or load it through constrain():
$book = Book::findOrFail($args['id']); $graphQLService->security()->assertCanView($book);
Custom Fields
You can add custom fields to your GraphQL types using the field() method.
$schema = new Schema([ 'query' => $graphQLService->query() ->view(Book::class) ->field('customField', [ 'type' => Type::string(), 'resolve' => function ($root, $args) { return 'Hello World!'; } ]) ->build(), ]);