Graphqlite Laravel Package

Technical Evaluation

Architecture fit

• GraphQLite is a code-first, attribute-driven schema layer for PHP. It sits between your Laravel application code and webonyx/graphql-php (the actual GraphQL execution engine), translating PHP attributes (#[Type], #[Field], #[Query], #[Mutation], #[Input], #[Security], #[Autowire]) into an executable schema at runtime.
• For a Laravel codebase, the value proposition is near-zero schema boilerplate: existing DTOs, Eloquent models, and service classes can be annotated in place, and controllers become resolvers. That is a materially lower adoption cost than schema-first alternatives (Lighthouse .graphql SDL files) or hand-wiring webonyx types.
• The package is framework-agnostic by design, with thecodingmachine/graphqlite-laravel (a separate, smaller package) providing the service provider, config publishing, and route registration. This is a double-edged property: it means the core is not Laravel-idiomatic (expect PSR-11 container abstractions and a middleware pipeline that is GraphQLite's own, not Laravel's), and it means you are adopting two packages with independent release cadences.
• The TPM framing matters here: GraphQLite is a schema generation accelerator, not a GraphQL platform. It does not ship DataLoader/batching, persisted queries, cost analysis, or Apollo-compatible caching semantics out of the box. Those are yours to build or buy.

Integration feasibility

• Low-to-moderate. Concretely: composer require thecodingmachine/graphqlite-laravel, publish config, define a types namespace/directory to scan, and the library reflects over those classes to build the schema. A working /graphql endpoint is achievable in a spike of a few days for a small domain.
• Laravel-specific integrations that exist and are worth verifying in the spike: autowiring resolvers from Laravel's container, Laravel Validator rules for #[Input]-based user input validation, and #[Security]/#[Security("is_granted(...)")]-style field-level authorization alongside Laravel Gates/Policies.
• Capabilities confirmed by the release history that map to real product needs: native PHP enums and union return types (v6.0.0), recursive #[Input] types and getter/setter-backed input fields (v6.0.0), custom input validators (v6.0.0), void resolvers (v6.2.1), file uploads via the optional ecodev/graphql-upload package (demoted to "recommended" dependency in v4.1.0 — you must add it explicitly).

Technical risk

• Version coupling and BC-break history. The project has shipped breaking or behavior-changing items in minor releases more than once: v4.1.0 (file-upload package moved to optional), v6.0.0 (#[Input] naming/default semantics changed; existing named input types without default silently change meaning), v6.1.0 (PSR-11 v2 required; interface signatures tightened — a hard break for anyone with custom type mappers), v4.0.2 (enum type naming BC break). A TPM must treat minor upgrades as potentially breaking and budget for it.
• Hard dependency on webonyx/graphql-php major versions (v14.9 from GraphQLite 5.x, v15 from 6.2.0) and on PHP ^8.1 floor with testing on 8.2. Your PHP upgrade cadence is therefore coupled to this package's cadence, not just to Laravel's.
• Community and bus factor. ~578 stars and 0 listed dependents is a small ecosystem relative to Lighthouse or webonyx directly. Release notes read as a small maintainer group with named individual contributors. There is real single-maintainer concentration risk, mitigated by MIT licensing and the fact that the output is a standard webonyx schema (so the escape hatch — hand-written type definitions — is viable, if laborious).
• Documentation debt around the Laravel path. README and release notes document the Symfony bundle's operational knobs (introspection disable, max query complexity, max query depth) far more explicitly than the Laravel equivalent. Assume those protections must be independently confirmed for the Laravel integration.
• Reflection-based schema building has failure modes at boot, not at request time. A historically documented example: a class with a bad namespace inside the scanned directory crashed schema construction (fixed in v4.0.1). This is a class of failure where a stray class in your types namespace takes down the entire endpoint.

Key questions to resolve before commitment

1. Does the Laravel integration expose query depth/complexity limits and introspection toggling at parity with the Symfony bundle? If not, what do we wrap around it?
2. Is there a supported, documented strategy for N+1 mitigation (DataLoader-equivalent)? If not, what is our batching layer?
3. Does the Laravel integration support subscriptions over WebSockets, or is that Symfony-only in practice?
4. What is the schema build cost per request, and does the attribute/annotation cache work correctly under php artisan config:cache and in a read-only container filesystem?
5. Who owns upgrading webonyx/graphql-php majors, and what is our tolerance for a breaking #[Input]-style change landing in a patch/minor?
6. What is the realistic fallback cost if the package is abandoned — i.e., how many types would we have to rewrite against raw webonyx?

Integration Approach

Stack fit

• Fits cleanly into a conventional Laravel app: service provider registration, publishable config for the scanned type namespace(s) and middleware, container-backed resolver autowiring, Laravel validator reuse for input types, and Gates/Policies reuse for authorization. Team skill required is "senior PHP/Laravel comfortable with reflection and attributes" — not "GraphQL spec expert" — which is the primary staffing advantage.
• Poorer fit where the organization needs schema-first governance (schema reviewed as an artifact in PRs, contract-first client codegen, public/partner API with consumers who need an SDL contract before implementation). GraphQLite is code-first: SDL is an output, not an input. If API governance requires schema review gates, plan to add a CI step that dumps SDL and diffs it.
• Poorer fit for teams already standardized on Lighthouse, or on a non-PHP BFF layer.

Migration path

• Greenfield endpoint on an existing Laravel app (recommended first move): mount GraphQLite at /graphql, scope its scanned namespaces to a small new domain, and leave REST untouched. This gives a real schema with zero blast radius on existing controllers.
• From an existing REST API: incremental strangler. Add #[Query]/#[Mutation] methods that delegate to existing application services/actions rather than reimplementing logic. The REST controller and the GraphQL resolver should be two thin adapters over the same service — this is the key discipline that keeps the migration reversible.
• From Lighthouse or rebing/graphql-laravel: not a mechanical translation. Lighthouse's directives/@field resolvers and rebing's config-driven type registry have no 1:1 mapping to attributes. Budget per-type manual work; reuse the business logic layer, rewrite the schema declaration layer.
• From Doctrine annotations in an existing GraphQLite 5.x/4.x codebase: mechanical but must be done, and should be done before adopting. v6.2.2 explicitly deprecates SchemaFactory::setDoctrineAnnotationReader in favor of native attributes. Combine this with the PHP 8.1 floor upgrade.

Compatibility

• Pin thecodingmachine/graphqlite, thecodingmachine/graphqlite-laravel, and webonyx/graphql-php with caret constraints and a committed lockfile, and treat the two GraphQLite packages as a single upgrade unit — do not upgrade the core without upgrading the Laravel bridge in the same PR.
• Verify PHP 8.1/8.2 support against your actual target runtime; 8.3+ support should be confirmed empirically, not assumed, from the release notes provided.
• File uploads require an explicit ecodev/graphql-upload dependency plus the PSR-7 implementation (laminas/diactoros lineage). Do not assume uploads work out of the box.
• Custom RootTypeMapperInterface implementations are a known breakage surface (v6.1.0 tightened signatures). Avoid extending the type mapper unless a requirement genuinely demands it.

Sequencing

1. Spike (1–2 sprints, timeboxed): one domain, 5–8 types, one query, one mutation, auth middleware, SDL dump. Validate the six open questions above — especially depth/complexity limits and N+1 behavior under a realistic query.
2. Design gates: SDL-diff CI job, schema caching strategy, error-shape contract (GraphQL errors vs. Laravel exception handler), authorization convention (#[Security] vs. Gates), and a decision record on the N+1 strategy.
3. Pilot in production behind a single consumer (ideally a first-party SPA or internal client) on a non-critical read path.
4. Broaden domain coverage only after one clean minor-version upgrade has been executed and rehearsed.
5. Decommission corresponding REST endpoints last, behind a deprecation window — GraphQLite makes it easy to add; it makes nothing easier about removing.

Operational Impact

Maintenance

• Ongoing maintenance is low in steady state, spiky at upgrade time. The library is declarative; adding a field is an attribute, not a config change. The recurring cost is the upgrade tax: PHP minor/major bumps and webonyx/graphql-php majors will force coordinated work, and the BC-break history says "minor" is not a safety guarantee.
• Assign an explicit owner for the three-package upgrade unit. Unowned dependencies with BC-break history become quarterly emergency work.
• The attribute cache and schema build should be part of deployment verification: a CI job that boots the app, builds the schema, and diffs the emitted SDL against a committed snapshot catches both accidental API breakage and the "bad class in the scanned namespace" class of failure before it reaches production.

Support

• In-house support burden is the dominant cost, not vendor support. There is no commercial backing implied by the sources: support is GitHub issues/discussions, community-driven, with a code-coverage and CI story that is genuinely good for a project this size but no SLA.
• Debuggability is a consideration: errors surface as schema-build exceptions at boot (clear but blunt, and potentially endpoint-wide) or as GraphQL execution errors mid-resolver (which must be mapped deliberately to your existing error/logging pipeline — Laravel's exception handler does not automatically know about GraphQL error formatting).
• Document the attribute vocabulary you actually use (#[Type], #[Input], #[Field], #[Security], #[Autowire], validation assertions) as an internal standard. The library permits many ways to express the same field; unconstrained, the schema will drift stylistically and become hard to review.

Scaling

• Request-level scaling is horizontal and unremarkable — resolvers run in normal PHP-FPM/Octane workers. Two caveats: Octane's long-lived workers interact with reflection/attribute caching and container state in ways that warrant explicit load testing; and schema build cost per worker boot must be measured, not assumed.
• The real scaling hazard is N+1 resolution. Because the library maps fields to arbitrary PHP callables with no batching primitive, a naive #[Field] public function getAuthor(): User on a list of 100 posts is 100 queries. This is the single highest-impact operational risk and it will not show up in a spike with 3 records. Mitigate with eager-loading discipline, a batching layer, or field-level lazy resolution — and enforce it with query-count assertions in tests.
• Query abuse is a second scaling hazard. Expensive or deeply nested queries are cheap for a client to write. Depth and complexity limits exist in the Symfony bundle's documented settings; confirm and, if necessary, implement the Laravel equivalent before exposing the endpoint beyond trusted clients. Introspection should be disabled in production unless it is a deliberate product decision.
• Subscriptions require a persistent transport and a pub/sub backend; treat this as out of scope for the first phase and validate separately.

Failure modes to design against

• Schema-build failure at boot from an unrelated class in a scanned namespace → total endpoint outage, not a degraded field. Mitigate by keeping scanned namespaces narrow and explicit rather than sweeping app/.
• Breaking change absorbed silently in a composer update → schema or input-type semantics shift under existing clients. Mitigate with the SDL snapshot diff in CI and a lockfile discipline.
• Unbounded query cost → database saturation from a single client request. Mitigate with depth/complexity limits and a per-client rate limit at the edge.
• File uploads without the optional package installed → confusing resolver-time failures. Mitigate by explicitly declaring the dependency if the feature is in scope, and by testing the upload path.
• Container/autowiring misconfiguration in resolvers → runtime errors that look like application bugs. Mitigate with integration tests that execute real GraphQL documents end to end, not just unit tests on resolvers.

Ramp-up

• Fast for Laravel developers, ~1–2 weeks to productive on attributes and the query/mutation model, because the mental model is "annotate a class, write a method."
• The non-obvious half is GraphQL itself, not GraphQLite: nullability semantics, error-vs-null propagation, connection/pagination conventions, input type design, and N+1 avoidance. Budget for that separately — it is where teams new to GraphQL produce APIs they regret in six months.
• Recommended onboarding artifacts: the internal attribute standard, one reference domain implemented end to end, an SDL-diff CI example, and a short "how to avoid N+1 here" guide. Two engineers trained plus one named owner is a workable operating model for a mid-size Laravel codebase.