Graphqlite Laravel Package

Product Decisions This Supports

• API strategy: code-first GraphQL vs. REST for a Laravel product. GraphQLite lets you expose existing Eloquent models/DTOs as GraphQL types via PHP attributes, so the decision "do we offer a GraphQL API" becomes an incremental delivery question rather than a re-architecture project. You can ship a read-only query surface first and layer mutations on the same annotated classes.
• Build vs. buy for the schema/plumbing layer. The undifferentiated heavy lifting — schema generation, type mapping, input coercion, validation wiring, authorization hooks, subscriptions, file uploads — is provided. Your engineering spend goes to resolvers and domain logic, not to a hand-rolled schema builder on top of webonyx/graphql-php.
• Feature-level scoping: which endpoints get GraphQL exposure and when. Because a single class can be both an output #[Type] and an #[Input] (fully matured in v6 with recursive input types, setters, and #[Input(default: …)] variants), you can decide per-domain whether it participates in the API without maintaining parallel input/output DTOs. This directly reduces the cost of incremental API surface expansion — useful when roadmap items are "expose orders to partners" rather than "rebuild the API".
• Roadmap input for mobile/partner/SPA clients. If your roadmap includes a first-party SPA, mobile app, or partner integrations that need flexible field selection and reduced round-trips, this package makes that roadmap item cheap enough to schedule. If your clients are server-to-server and fixed-shape, it does not unlock anything.
• Authorization and validation placement decisions. #[Security] / fine-grained field-level security and Laravel-validator-backed input validation mean access-control policy can live at the schema boundary instead of being duplicated in every controller. That is a policy decision worth making explicitly (schema as policy layer vs. service layer), and this package supports the former.
• Buy-vs-extend for adjacent capabilities. File uploads, subscriptions, and custom type mappers are present but the upload path requires an extra dependency (ecodev/graphql-upload is "recommended," not bundled) — a scoping decision you must make up front rather than discover mid-sprint.
• Use cases this fits: internal admin/tooling APIs where clients are first-party, BFF layers in front of a Laravel monolith, partner APIs that need field selection and versionless evolution, and incremental strangler-style exposure of an existing Laravel domain.
• Decisions this does not support: choosing a GraphQL federation platform, a schema-first/design-first workflow where the SDL is the contract (GraphQLite is code-first and the SDL is a derived artifact), or a public API where the schema must be reviewed and versioned independently of PHP classes.

When to Consider This Package

Consider it when:

• You are on Laravel (or Symfony) and already have PHP domain objects — Eloquent models, DTOs, value objects — that you want to expose without writing a parallel schema by hand. The dedicated graphqlite-laravel integration is the intended path; do not hand-wire the core package to Laravel.
• Your team is PHP-fluent and PHP 8.1+ — the package targets PHP ^8.1 and leans on native attributes, native enums, union return types, and generics-in-phpdoc. Teams still on annotations or older PHP should stop here.
• You want code-first as the operating model: the schema is generated from attributes, the type system is the PHP type system, and you accept that the SDL is an output rather than a hand-authored contract.
• You need more than a toy: queries, mutations, subscriptions, iterators/array mapping, extendable types, input validation, and field-level security are all in scope. Many lightweight PHP GraphQL options stop well short of this.
• You can absorb a smaller ecosystem: the package is MIT, actively maintained with a real release history through v6.x, but the community is modest (~578 stars, no downstream dependents surfaced). That is acceptable for an internal or partner-facing surface; it is a real consideration for a public API with a decade-long support expectation.
• You are prepared to pin versions and read changelogs. This project has shipped behavioral and BC changes in minor releases (e.g., PSR-11 v2 requirement and interface signature changes in 6.1.0; #[Input] naming/default semantics in 6.0.0; the GraphQL upload dependency becoming optional/recommended in 4.1.0). Budget for upgrade work, not just composer update.
• You can own the operational surface: cache configuration for annotation/attribute metadata, introspection disabling, max query depth and complexity limits. These exist but they are settings you must turn on deliberately.

Look elsewhere when:

• You want a schema-first / SDL-first contract, or your API is designed by a separate consumer team and handed to PHP as a spec. GraphQLite inverts that.
• Your stack is not Laravel/Symfony or not PHP — the framework-agnostic core exists, but the value proposition is the integration.
• You need schema federation, stitching, or a GraphQL gateway as a first-class concern.
• You require enterprise support, an SLA, or a large hiring pool of practitioners. The maintainer concentration around a single organization (thecodingmachine) is a continuity risk to price in.
• Your queries are high-throughput and latency-critical and you cannot afford attribute/reflection-driven schema generation without carefully tuned caching — validate this with a load test rather than assuming.
• You have a small surface area (a handful of endpoints, fixed shapes). The overhead of GraphQL and a metadata layer will not repay itself.
• You need the upload feature and expected it bundled — it isn't; that's an added dependency and an added security review item.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can expose our existing Laravel domain as a GraphQL API without a rewrite. GraphQLite generates the schema from PHP attributes we attach to classes we already own, which means the cost of the API is our resolvers, not a new abstraction layer — and it converts "GraphQL" from a multi-quarter platform initiative into a per-domain, schedulable line item we can ship and expand feature by feature. It is MIT-licensed with no per-seat cost and no vendor lock-in, so the downside is bounded to engineering time we would spend anyway. The trade-off we are accepting is a smaller open-source community and a maintainer concentration risk, which we mitigate with pinned versions, a locked upgrade cadence, and — because everything is plain PHP on top of webonyx/graphql-php — a realistic exit path if the project stalls.

For engineering (the working summary):

• What it is: a code-first GraphQL schema generator for PHP 8.1+. #[Type], #[Field], #[Input], #[Mutation], #[Query], #[Security] on your existing classes and controller methods produce a complete, spec-compliant GraphQL schema executed by webonyx/graphql-php. Use the graphqlite-laravel package, not the core package directly.
• Why it fits us: one class can serve as both output type and input type (v6 matured recursive input types, setters on #[Input] fields, and multiple named input variants off a single class). We avoid the classic duplication of Eloquent model + GraphQL DTO + request validator.
• What it buys us out of the box: queries, mutations, subscriptions, arrays/iterators mapping, native enums, union return types, generic phpdoc iterables, file uploads, extendable types, custom input validators, field-level security via #[Security], autowiring in resolvers, and #[deprecated] propagating to the schema. Introspection toggling, max query complexity, and max query depth are configurable — we should enable them from day one, not after an incident.
• What it does not buy us: schema-first governance, federation, enterprise support, or a large talent pool. File uploads require adding ecodev/graphql-upload as a separate dependency and reviewing it.
• Known cost: the project has a history of BC breaks in minor versions (4.1.0, 6.0.0, 6.1.0). We pin exact versions, treat upgrades as scheduled work with a test suite covering our schema snapshot, and keep our resolvers thin so the metadata layer stays swappable.
• Definition of done for a spike: one read path and one write path exposed end-to-end on a real domain, schema snapshot in CI, caching and query-depth limits configured, and a measured p95 on a representative query — then decide whether to broaden.