Butler Graphql Laravel Package

Getting Started

Butler GraphQL is a Laravel package that generates a GraphQL API from your Eloquent models with minimal configuration. Install via Composer:

composer require glesys/butler-graphql

Publish the config and generate the schema from your models:

php artisan vendor:publish --tag=butler-graphql-config
php artisan butler:generate

Look first at config/butler-graphql.php (type mappings, model discovery paths, middleware) and the generated schema file. A good first use case is exposing a single read-only model — e.g. a Post model with title/body fields — as a queryable type, then adding relations once the basics work.

Implementation Patterns

• Model-driven schema generation: Expose models by convention (config-driven discovery) rather than hand-writing SDL; regenerate after model changes. Keep generated schema under version control if you need reviewable diffs of your API surface.
• Custom scalars for domain types: As of v13.1.0 you can register custom scalar types, which is the idiomatic way to handle things like money, UUIDs, dates, or geospatial values that don't map cleanly onto built-in GraphQL scalars. Define the scalar in your GraphQL config and pair it with a PHP conversion/parsing class so Eloquent attribute values and GraphQL values stay symmetric.
• Relations as nested fields: Model relationships (hasMany, belongsTo, belongsToMany) become nested GraphQL fields; use eager loading configuration or query-scope hooks to avoid N+1 explosions on nested resolvers.
• Local vs HTTP schema: Typically run schema generation in local/CI and serve via the HTTP endpoint in staging/production; keep the two paths in sync by making generation part of your deploy or build pipeline.
• Testing: Point your GraphQL test suite (e.g. Pest/PHPUnit with snapshot or assertion-based queries) at the generated schema so schema drift is caught before deploy.

Gotchas and Tips

• Regenerate after every model change. Butler derives the schema from your models; stale generated artifacts are the most common source of "field doesn't exist" confusion. Wire butler:generate into a Composer script or CI step.
• Custom scalars (v13.1.0) need both sides defined. Registering a scalar name isn't enough — you must supply serialization/parsing logic, or values will come back as strings or fail validation. Test scalar round-trips with queries that exercise input and output.
• N+1 queries are the main debugging trap. Nested relation fields resolve lazily; enable query logging in development, and use eager-load/DataLoader-style batching patterns for hot paths.
• Guard your schema. Add authentication/authorization middleware at the config level and use per-type or per-field authorization hooks so exposing a new model doesn't accidentally widen your API.
• Config quirks: model discovery paths, namespace conventions, and type mappings are read at generation time — config changes require regeneration, not just a cache clear.
• Extension points: for anything the generator doesn't cover, prefer custom scalar registration, custom type mappings, and resolver overrides over post-editing generated files, which get overwritten.
• Upgrade note: v13.1.0 is additive (custom scalar support) with no breaking changes reported; no API/schema changes required to upgrade from v13.0.0, but re-run schema generation and your test suite after bumping.