Butler Graphql Laravel Package

Technical Evaluation

Baseline note: No prior assessment exists for glesys/butler-graphql, so this establishes the baseline. It is triggered by v13.1.0 and inferred from the release signal plus the package's role as a Laravel GraphQL server layer. Assumptions are flagged; the open questions below should be closed before committing.

Architecture fit

• Butler sits between Laravel's HTTP/kernel layer and domain services, translating GraphQL documents into resolvers backed by Eloquent, policies, and the service container. It is a BFF/API-composition layer, not a domain framework.
• v13.1.0 adds custom scalar support — a genuine capability gap for most production schemas. Domain value types (money, UUIDs, dates with timezone, enums-as-scalars, structured JSON, geo coordinates) can now be typed at the schema boundary instead of being stringly-typed and validated ad hoc in resolvers.
• This improves contract clarity for client teams and shrinks resolver-level validation code, which is a maintainability win rather than an architectural change. Nothing in the release alters the execution model, so the existing fit assessment is unchanged.

Integration feasibility

• The change is additive and non-breaking: a minor version bump on an established 13.x line. Adoption cost is a composer update plus registering scalar implementations in the type/schema configuration.
• No schema migration is required for existing APIs. Scalars are opt-in — teams can adopt one or two (DateTime first, typically) and defer the rest.
• Real cost is writing correct parseValue / parseLiteral / serialize implementations. That is per-scalar engineering, not integration engineering.

Technical risk

• Release risk: low. Additive feature, minor semver, single PR. Standard lockfile-plus-CI gating is sufficient.
• Custom scalar implementation risk: moderate. Hand-written scalars are a common source of subtle defects: timezone and precision drift on date scalars, permissive JSON scalars that bypass schema validation entirely, and parseLiteral paths that diverge from parseValue behaviour. Treat each scalar as production code with its own test matrix.
• Input-surface risk. A loose JSON or Mixed scalar can re-open injection and payload-size vectors that a strongly typed schema would have closed. Any such scalar needs explicit depth/size limits at the middleware layer.
• Supply-chain risk: moderate-to-high. Transitive dependency on webonyx/graphql-php; the scalar interface is defined upstream, so a graphql-php major can force a Butler major. Maintainer concentration (single-organisation package) is a bus-factor concern for a component on the critical API path.

Key questions

1. Which Laravel and PHP versions does 13.x support, and what is the support window? Is there a published upgrade guide from 12.x?
2. Are custom scalars registered globally, per-schema, or per-type? Does registration interact with the schema cache?
3. Do scalar parse failures surface as spec-compliant GraphQL errors (400-class) rather than uncaught exceptions (500-class)?
4. Does the scalar layer compose with Butler's field-selection / eager-loading optimisation, or does it force full hydration?
5. What is the pinned webonyx/graphql-php constraint, and how tightly is it coupled to the Butler major?
6. Release cadence, CVE history, and maintainer headcount for the upstream repo.

Integration Approach

Stack fit

• Laravel 10/11/12 with PHP 8.1+, Composer-managed, standard service-provider registration and config publishing. Fits the existing conventions of an Eloquent-centric Laravel codebase with no new runtime (no Node sidecar, no separate schema server).
• Pairs cleanly with existing auth middleware and policies — authorization stays in Laravel, which keeps the security model familiar to the team.
• Best positioned as a client-facing BFF for web and mobile, with REST retained for internal service-to-service calls where GraphQL's flexibility adds no value.

Migration path

• Greenfield GraphQL: adopt 13.1.0 directly, define scalars from the outset — cheaper than retrofitting.
• Existing Butler 12.x: the 12→13 step is the major-risk item, not 13.1.0. Read the 13.0.0 changelog for removals and renamed APIs, upgrade in a branch, then take 13.1.0 as a fast-follow once green.
• REST-only today: introduce GraphQL as an additive read-path first (queries only), keeping mutations on REST until the team is fluent. This de-risks the learning curve and keeps rollback trivial.

Compatibility

• Verify the pinned webonyx/graphql-php version and confirm the custom scalar contract matches what the team intends to implement.
• Confirm schema-cache behaviour in the target environment — cached schemas must be rebuilt on deploy, and adding scalars changes the schema hash.
• Check that any client codegen (Apollo, graphql-codegen) has mappings for custom scalars; unmapped scalars silently degrade to any in TypeScript and erode the type safety the feature was meant to deliver.

Sequencing

1. Sandbox spike: install 13.1.0, implement one DateTime scalar, confirm error semantics and schema caching.
2. Add depth/complexity limiting and confirm scalar input is constrained before any external exposure.
3. Ship read-only queries to a low-traffic consumer; instrument resolver timings.
4. Expand to mutations; add remaining scalars (UUID, Money, JSON) with per-scalar test suites.
5. Publish an internal scalar registry doc so teams don't hand-roll duplicates.

Operational Impact

Maintenance

• Low ongoing effort: periodic Composer updates and a review of release notes. The main recurring task is curating the scalar registry so the codebase doesn't accumulate three competing DateTime scalars.
• Given the maintainer concentration, plan for the possibility of abandonment. Mitigation is thin — pin versions, keep the integration surface narrow (avoid deep reliance on Butler internals), and be prepared to fork or replace with a plain graphql-php + Laravel integration if upstream stalls. Budget a contingency note, not a project.

Support

• On-call must distinguish GraphQL-layer faults from domain faults. Scalar parse errors are a new failure class and should be logged with the scalar name and offending input (redacted) so triage doesn't require reproducing the client document.
• Client teams need a published contract for each scalar (format, range, nullability, error behaviour). Undocumented scalars generate support load disproportionate to their complexity.

Scaling

• Custom scalars do not change the scaling profile; N+1 resolution remains the dominant risk. Keep depth and complexity limits, persisted queries, and query-cost budgets in place regardless.
• Watch response-size growth if a permissive JSON scalar is introduced — it can quietly inflate payloads and defeat CDN caching heuristics.

Failure modes

• Uncaught scalar exception → 500 instead of a field-level GraphQL error, degrading the whole response for a single bad input. Test this explicitly.
• Stale schema cache after deploy → resolver or scalar registration mismatches, producing confusing runtime errors that don't reproduce locally.
• Transitive graphql-php bump → breaking changes in the scalar interface at an inconvenient time; pin and upgrade deliberately.
• Overly permissive scalar → validation bypass leading to injection or resource-exhaustion vectors.
• Client codegen gap → silent any typing that removes the safety the schema was supposed to provide.

Ramp-up

• A Laravel-fluent engineer reaches productive query/mutation work in roughly one to two sprints; the mental model shift is GraphQL schema design and resolver discipline (batching, field selection), not Butler's API.
• Custom scalars add about a day of learning plus per-scalar implementation and testing time. Assign ownership early — this is exactly the kind of capability that gets duplicated across teams without a named owner and a short written standard.