Graphql Controllers Laravel Package

Technical Evaluation

Architecture fit

• The package is a controller-centric GraphQL execution layer built on top of webonyx/graphql-php (the de facto PHP GraphQL reference implementation). It is framework-agnostic, not Laravel-specific: it resolves schema fields to methods on plain PHP classes annotated with @Query / @Mutation / @Field, and pulls collaborators from a PSR-11 container.
• Fit is best where the team already thinks in "service class → method → resolver" terms and wants the schema to be derived from code rather than authored as SDL. It is a poor fit for teams standardized on SDL-first workflows (Lighthouse-style .graphql files), because the schema becomes an output of PHP annotations and is no longer a reviewable artifact in isolation.
• It is the lower-level engine that underpins thecodingmachine/graphqlite. For a new build, adopting the engine directly rather than the higher-level, better-maintained sibling is a material architectural decision, not a detail.

Integration feasibility

• Installable via Composer and executable behind a single Laravel route. Laravel's container satisfies PSR-11, so constructor injection of application services into controllers largely works out of the box.
• Not turnkey: there is no Laravel service provider, no published config, no auth/policy bridge, no GraphiQL/IDE route, no query-complexity guardrails. Expect 1–2 weeks of glue work for a production-grade endpoint (schema cache wiring, error formatting, middleware, authorization hooks, request logging).
• Annotation parsing is expensive; a PSR-16 cache adapter must be bound and the cache key versioned per deploy, or every request pays schema-build cost. This is the single most common integration failure.

Technical risk — high

• Maintenance signal: 11 stars, last release February 2023, single-vendor origin, no visible security response process. For a dependency that sits on the public API surface, this is the dominant risk.
• Runtime compatibility: no evidence of PHP 8.3/8.4 or Laravel 11/12 validation. Laravel's upgrade cadence will outpace this package. Must be proven on the target matrix before commitment.
• Annotation paradigm: docblock annotations are a legacy pattern; PHP 8 attributes may not be supported, degrading static analysis, IDE navigation, and refactor safety across a growing schema.
• Transitive exposure: inherits webonyx/graphql-php major-version churn without guaranteed upstream alignment.
• Opportunity score (0.76) indicates niche-but-real interest; it does not offset the bus-factor concern.

Key questions for the vendor/OSS evaluation

1. Has the package been exercised on our target PHP and Laravel versions, with a CI matrix we can inspect?
2. Does it support PHP 8 attributes, or only doctrine annotations?
3. What is the N+1 mitigation story (prefetch/eager-load/deferred resolvers) for nested queries?
4. Is webonyx/graphql-php pinned to a supported major, and who bumps it?
5. Is there a maintained alternative that gives the same authoring style (graphqlite) and does it justify the hedge?

Integration Approach

Stack fit

• GraphQL endpoint as a thin Laravel controller → package execution layer → webonyx → application services. Authentication via existing Laravel middleware; authorization must be implemented explicitly — there is no Gate/Policy mapping, so field-level and object-level checks belong in the resolver layer or a custom field middleware. Plan for this in estimates; it is the most frequently underestimated work item.
• Cache bindings: PSR-16 adapter over Laravel's cache store, keyed by deploy SHA. Container binding: app() passed as the PSR-11 implementation.

Migration path

• Do not rip out a working REST or SDL-first GraphQL layer for this. Introduce it as an additive, side-by-side endpoint and strangle traffic domain by domain — reads first, writes later.
• If the team is currently on Lighthouse or rebing/graphql-laravel, treat migration as a resolver rewrite, not a port: the schema is regenerated from annotations, so SDL becomes an output, not an input. The business case for that churn is weak unless there is a specific ergonomics complaint.

Compatibility

• Verify the Composer graph resolves cleanly against the existing dependency set before any design work; conflicts on webonyx/graphql-php constraints are likely and are a hard blocker if other packages pin it.
• Confirm framework version bounds against the Laravel release the platform is on today and the next one planned.

Sequencing

1. Week 1 — spike: throwaway branch, one read-only domain, real data volume; measure schema-build cost, cold/warm latency, and N+1 behavior.
2. Week 2 — hardening: schema cache, error masking, complexity/depth limits, authorization hooks, query logging, GraphiQL gated to non-prod.
3. Week 3 — decision gate: if the spike shows acceptable latency and the glue code is modest, proceed with a pinned version and a documented fork plan; otherwise adopt graphqlite (same style, larger community) or Lighthouse (Laravel-native), and record the rationale.
4. Post-decision: full bounded-context rollout, one domain per sprint, with the REST endpoint retained as fallback.

Operational Impact

Maintenance

• Treat as vendored-in-all-but-name: pin an exact version, forbid transitive wildcards, and pre-commit to a fork-and-patch contingency (a maintainer-day or two per year) if the upstream goes quiet. Subscribe to PHP/Laravel release notes and re-validate on every platform upgrade.
• Doctrine annotations are on a deprecation trajectory; budget for a future attribute migration or a schema-generation rewrite.

Support

• Effectively no community: 11 stars means sparse issue triage, thin Stack Overflow coverage, and no commercial backing. Internal ownership must be named — one engineer accountable for the GraphQL layer, with a second able to operate it.
• Institutional knowledge concentrates on webonyx semantics (type system, execution, error format), which is transferable and well documented. The package-specific surface is small; the risk is concentrated in the unmaintained edge, not the concept.

Scaling

• The HTTP tier is stateless and scales horizontally without ceremony.
• Two real bottlenecks: (a) schema construction/annotation parsing — mitigate with OPcache/preloading plus a warm PSR-16 schema cache, and assert on it in load tests; (b) N+1 database access on nested fields — mitigate with prefetching and per-request dataloaders. Both are configuration-and-discipline problems, not framework limits.
• Add query depth/complexity limits and per-client rate limiting at the edge; the package does not provide them and a public GraphQL endpoint without them is a denial-of-service surface.

Failure modes

• Boot-time fatal: invalid annotation or container binding kills the whole application, not just /graphql. Guard with a health check that exercises schema construction.
• Stale schema after deploy: version the cache key by release SHA; otherwise a deploy silently serves the previous schema.
• Information disclosure: default error output can leak stack traces and SQL; enforce environment-scoped debug messaging and a sanitizing formatter.
• Unbounded queries: deep or expensive queries degrade the shared database; depth/complexity limits are mandatory, not optional.
• Upgrade break: PHP or webonyx major bump lands with no upstream patch — the fork contingency becomes live.

Ramp-up

• 2–3 weeks for a mid-level Laravel developer to be productive: GraphQL concepts plus annotation-driven schema derivation is a genuine paradigm shift, and SDL-first habits actively mislead here.
• Add review discipline for schema changes — because the schema is generated, a diff review does not surface the API contract change. Introduce a committed schema-dump artifact in CI so breaking changes are visible in pull requests.