Graphqlite Bundle Laravel Package

Getting Started

GraphQLite is an attribute/annotation-driven GraphQL schema generator for PHP. The thecodingmachine/graphqlite-bundle release (v7.6.0) is the Symfony bundle wrapper, but the underlying thecodingmachine/graphqlite library is framework-agnostic and is what Laravel developers typically wire into a Laravel app directly or through a Laravel-specific integration package. Treat the bundle release notes as signal about the core library’s behavior, especially around schema caching.

Minimal setup for a Laravel app:

1. Install the core library and a PSR-7/HTTP bridge appropriate for your stack:

   composer require thecodingmachine/graphqlite
   

2. Create a GraphQL endpoint controller and point a route at it:

   Route::post('/graphql', GraphqlController::class);
   

3. Define your first type and query using attributes:

   #[Type]
   class User {
       #[Field]
       public function name(): string { return $this->name; }
   }
   
   class UserQuery {
       #[Query]
       public function user(int $id): ?User { return User::find($id); }
   }
   

4. Register the controller/namespace so GraphQLite can discover types and queries.
5. Open your GraphQL client against /graphql and run { user(id: 1) { name } }.

Where to look first: the attribute classes under GraphQLite\Annotations (#[Type], #[Query], #[Mutation], #[Field], #[Input], #[Security]), the schema factory configuration, and the caching layer introduced/changed in this release.

Implementation Patterns

Attribute-first schema definition. Keep one PHP class per GraphQL type and colocate fields, input types, and factories. Use #[Input] plus #[Field] for mutation payloads, and #[Factory] for constructing types from arrays or models.

Thin resolvers, fat domain layer. Query and mutation methods should delegate to services, actions, or Eloquent queries. This keeps GraphQL classes easy to test and avoids coupling your schema to persistence details.

Explicit type mapping. For Eloquent models, either map them with #[Type] and #[Field] methods or use dedicated GraphQL type classes and #[Factory] methods. Prefer explicit mapping to avoid leaking database column names into the public schema.

Security at the schema boundary. Use #[Security] expressions or a custom authorization middleware for field-level and mutation-level checks. For Laravel, map these checks onto Gates and Policies inside the resolver or via a custom AuthorizationService.

Schema caching as a deploy step. With v7.6.0, schema caching is applied automatically in any environment where debug is disabled. For Laravel this means production, staging, and often CI. Treat schema compilation like config caching:

php artisan graphql:schema-cache   # or your integration's equivalent

Warm the cache during deployment after code is in place.

HTTP integration. Wire the GraphQL endpoint through a single Laravel controller, parsing the GraphQL request, invoking the schema, and returning a PSR-7 or Laravel response. Keep middleware for auth, CORS, and request logging at the route level rather than inside resolvers.

Testing pattern. Test GraphQL operations by posting queries to the route or invoking the schema executor directly, asserting on the data and errors keys. Keep a small set of schema snapshot tests to catch accidental breaking changes to field names and nullability.

Pagination and errors. Use cursor-based pagination for large collections and a consistent error shape. GraphQLite’s exception handling can mask internal errors in production; ensure domain exceptions are converted to user-safe GraphQL errors.

Gotchas and Tips

Schema caching now applies beyond production. The v7.6.0 change caches the schema in every environment that runs without debug, not only in prod. In Laravel terms, if APP_DEBUG=false, your schema is cached. Attribute changes, new fields, or renamed types will not appear until the cache is cleared or rebuilt. Add a cache-clear or cache-warm step to your deploy pipeline.

Staging and CI surprises. Environments that historically ran with debug off but were treated like development will now serve a cached schema. If CI runs schema introspection or code generation against a staging URL, stale caches can produce confusing failures. Explicitly clear the schema cache before schema-dependent jobs.

Debug mode disables caching. Running with debug enabled avoids stale-schema issues but loses the performance benefit and can expose verbose errors. Do not leave debug on in production to work around cache problems; fix the deploy step instead.

Cache invalidation on multi-node deployments. If you run multiple app servers, ensure the schema cache is written to a shared location or rebuilt on every node. Local file caches can drift between servers.

Dependabot noise. Most of the v7.6.0 changelog is GitHub Actions dependency bumps. These do not affect runtime behavior; the meaningful change is schema caching.

Nullability and arrays. GraphQLite infers nullability from PHP types, but arrays and nullable collections are easy to get wrong. Use explicit #[Field] type declarations when the inferred schema is not what clients expect.

N+1 queries. Field resolvers that lazy-load relationships can trigger N+1 queries. Use eager loading in query resolvers or a dataloader pattern for nested fields.

Security expressions are not Laravel policies. #[Security] expressions use Symfony-style authorization semantics in the bundle. In a Laravel integration, verify how your adapter evaluates these expressions, or implement authorization explicitly in resolvers to avoid a false sense of protection.

Error masking. In production, unexpected exceptions may be replaced with generic GraphQL errors. Log the original exception with enough context to debug, and test that expected domain errors remain visible to clients.

Extension points. Custom scalars, middleware, and type mappers are the safest places to adapt GraphQLite to Laravel conventions. Prefer these over forking schema generation or patching vendor code.