Weave Code
Butler Graphql Laravel Package
glesys/butler-graphql
A Laravel package for adding a GraphQL API to your application. Define schemas, types, queries, and mutations, resolve data from your app, and expose a configurable GraphQL endpoint for flexible, typed client requests.
An opinionated GraphQL package for Laravel.
Frequently asked questions about Butler Graphql
- How do I install glesys/butler-graphql in a Laravel application?
- Install it with Composer via composer require glesys/butler-graphql, then publish the package configuration with the vendor:publish Artisan command and register your schema. Butler is a standard Composer-managed Laravel package, so it uses the usual service-provider registration and config-publishing conventions rather than introducing a new runtime or Node sidecar. Check the repository README for the exact config key names and the expected schema file location.
- Which Laravel and PHP versions does butler-graphql 13.x support?
- The package is on an established 13.x line and the current release is 13.1.0, which adds custom scalar support as an additive, non-breaking change. The evaluation for this package assumes Laravel 10, 11, or 12 with PHP 8.1 or newer, but that is an assumption rather than a confirmed matrix. Before committing, read the composer.json constraints and the release notes to confirm the supported Laravel and PHP range and the maintenance window for 13.x.
- How do I define schemas, types, queries, and mutations with Butler GraphQL?
- Butler is an opinionated GraphQL server layer: you declare schema types, queries, and mutations in configuration and PHP classes, then back each field with a resolver that pulls data from Eloquent, policies, and the service container. It sits between Laravel's HTTP layer and your domain services, so GraphQL documents are translated into resolver calls rather than bypassing your application code. The package only exposes a single configurable GraphQL endpoint, so most of the work happens in schema definition rather than routing.
- What problem do custom scalars in butler-graphql 13.1.0 solve?
- Custom scalars let you type domain value objects at the schema boundary instead of falling back to String or JSON and validating ad hoc inside resolvers. Money, UUIDs, timezone-aware dates, enums-as-scalars, structured JSON, and geo coordinates can all be declared as first-class types, which makes the contract clearer for client teams and shrinks resolver-level validation code. This is a contract-clarity and maintainability improvement, not a change to the execution model.
- Are custom scalars registered globally, per-schema, or per-type, and do they interact with the schema cache?
- Registration scope is the key thing to confirm in the package source before you build on it: the assessment flags global versus per-schema versus per-type registration as an open question, so verify which one Butler 13.1.0 implements. If your application caches the compiled schema, remember that scalar classes are part of that schema definition and must be cleared or rebuilt when registration changes. Adopt scalars incrementally, starting with one such as DateTime, so a registration mistake cannot break every type at once.
- Do custom scalar parse failures return proper GraphQL errors or uncaught 500s?
- Hand-written parseValue, parseLiteral, and serialize implementations are the most common source of subtle scalar defects, so confirm that a bad input value surfaces as a spec-compliant GraphQL error with a 400-class response rather than an uncaught exception producing a 500. The riskiest pattern is a parseLiteral path that behaves differently from parseValue, which lets a value pass through inline query literals but fail when supplied as a variable. Treat every scalar as production code and write tests that exercise both the variable and the literal paths.
- How does authorization work with butler-graphql in a Laravel app?
- Authorization stays in Laravel: Butler resolves fields through the service container, so existing middleware, gates, and model policies remain the enforcement point instead of a parallel GraphQL-only permission system. That keeps the security model familiar to a team already using Eloquent and policies. The practical caveat is that field-level and nested-resolver authorization must be applied deliberately, because a single top-level query can fan out into many resolvers.
- How do I test a butler-graphql endpoint and its custom scalars?
- Test the endpoint the same way you test any Laravel HTTP route, sending GraphQL documents and asserting on the JSON response, then add a dedicated matrix per custom scalar covering valid values, rejected values, variable input, and inline literal input. Scalars deserve their own tests for timezone and precision drift on dates and for permissive JSON handling. Also add a test that an invalid scalar input produces a client error rather than a server error, so regressions in error mapping are caught early.
- What are the production security risks of loose JSON or Mixed scalars?
- A permissive JSON or Mixed scalar can reopen payload-size and injection vectors that a strongly typed schema would have closed, because it bypasses the schema-level validation that makes GraphQL safer than free-form endpoints. If you adopt one, enforce explicit depth and size limits at the middleware layer and keep query complexity or depth limiting configured for the endpoint as a whole. Prefer narrow domain scalars, such as a typed date or money scalar, over a general-purpose JSON escape hatch wherever a concrete type is possible.
- How does butler-graphql compare to Lighthouse, and what are the maintenance risks?
- Butler is deliberately opinionated and resolver-class oriented, so it tends to suit teams that want GraphQL as a thin BFF layer over Eloquent and existing domain services, while other Laravel GraphQL packages lean more heavily on SDL-first, directive-driven schemas. Two risks are worth pricing in: the package depends on webonyx/graphql-php, and a major in that upstream library can force a Butler major because the scalar interface is defined upstream, plus it is a single-organisation package on a critical API path. Pin the graphql-php constraint, review release cadence and CVE history for both repos, and keep the GraphQL layer thin enough that replacing it stays feasible.
Weaver
How can I help you explore Laravel packages today?