Lighthouse Laravel Package

Technical Evaluation

Architecture fit. Lighthouse is a strong fit when the target API is a Laravel application that already relies on Eloquent, policies, validation, queues, and Laravel’s auth stack. It lets the team expose a schema-first GraphQL API without introducing a separate Node/Apollo service, and its directive model maps common API concerns — auth, pagination, validation, nested mutations, model binding, scopes — directly into the schema. That is attractive for a TPM because it reduces platform sprawl and lets Laravel engineers deliver GraphQL with familiar primitives.

It is a weaker fit when the organization needs a language-neutral GraphQL gateway, full Apollo Federation composition, heavy event-driven microservice aggregation, or a GraphQL layer owned by a dedicated platform team outside Laravel. Lighthouse can support advanced patterns such as subscriptions and federated tracing, but those should be validated as explicit requirements rather than assumed.

Integration feasibility. Integration is feasible as a Composer package with a Laravel service provider, configuration, schema files, and Artisan tooling. The changelog shows active compatibility work for Laravel 12 and 13, PHPUnit 12 test utilities, Laravel Reverb subscriptions, encrypted subscription channels, persisted queries, and schema/query caching. A pilot can be stood up in days, but production readiness depends on auth-policy correctness, query complexity controls, cache/deploy procedures, and subscription infrastructure if needed.

Technical risk. The largest non-technical risk is the announced repository move from nuwave/lighthouse to spawnia/lighthouse. A TPM should treat this as a supply-chain and ownership transition: confirm Packagist package continuity, namespace stability, documentation URL changes, security advisory routing, and maintainer support expectations. The code namespace may remain stable, but the Composer package identity and CI references must be verified before adoption.

Other risks: only the current major version receives features and fixes, so upgrades require deliberate cadence; the directive DSL is powerful but can obscure resolver behavior and create “schema magic”; nested mutations can create partial-write and transaction concerns; N+1 queries and unbounded GraphQL selections are common failure modes; subscriptions add Redis/broadcaster/websocket operational load. Lumen support is deprecated, so Lumen-based services should not adopt it. The supplied “last release: 2026-10-25” is future-dated relative to the review window, and “Dependents: 0” conflicts with the package’s visible maturity — both should be validated against Packagist before relying on them.

Key questions.

• Is GraphQL a product requirement, or would a well-designed REST/JSON:API layer satisfy the same consumers with less operational complexity?
• Is the application Laravel-only, and which Laravel/PHP versions must be supported?
• Do we need subscriptions, persisted queries, federation, or a public schema? If yes, who owns the websocket/cache/gateway infrastructure?
• What is the maintainer transition plan for spawnia/lighthouse, and will security advisories and releases continue under a predictable process?
• Who owns schema governance, directive standards, authorization review, and breaking-change policy?
• What are the latency, query-complexity, and availability SLOs for the GraphQL endpoint?
• Are we prepared to run schema CI, contract tests, load tests, and cache-clear deploy steps?

Integration Approach

Stack fit. Adopt Lighthouse when the service is a conventional Laravel app using Eloquent and Laravel’s auth/policy system. Pin to the current Lighthouse 6.x line and verify the exact Laravel/PHP/webonyx-graphql-php compatibility matrix. If the service is on Lumen, stop and replan. If the service uses Laravel Octane, queues, Redis, and broadcasting, include those in the compatibility spike rather than treating them as later concerns.

Migration path. Use an incremental “GraphQL facade” strategy rather than a rewrite. Start with read-only queries over existing Eloquent models and domain services, using Lighthouse directives such as @paginate, @find, @can, and @whereConditions. Keep REST endpoints live in parallel. Add mutations only after authorization, validation, idempotency, and transaction behavior are proven. Use existing Laravel policies and guards rather than building a parallel auth model. For legacy controller logic, wrap services with field resolvers rather than duplicating business rules in schema directives.

Compatibility. Pin the major version and validate transitive dependencies in CI. Confirm that the repository move does not change the Composer package name or namespace expected by the application. Test with the actual auth guards, policy registration, Redis/cache configuration, broadcasting driver, and deployment topology. If subscriptions are in scope, prove Redis/Reverb/Pusher behavior and channel authorization in a pre-production environment.

Sequencing.

1. Spike: install in a non-production branch; model two or three domains; test auth, pagination, nested reads, query complexity, and cache commands.
2. Pilot: expose read-only queries to an internal consumer; add schema linting, IDE helper generation, contract tests, and observability.
3. Mutation rollout: add create/update/delete and nested mutations with transaction tests, policy tests, and audit logging.
4. Scale features: introduce persisted queries, schema/query cache, rate limiting, and complexity limits based on measured traffic.
5. Subscriptions: only after broadcaster and websocket ownership is clear.
6. REST consolidation: retire or freeze REST endpoints only when consumer migration and rollback plans are proven.

A TPM should gate each phase on security review, performance benchmarks, error-rate thresholds, and consumer adoption — not on “schema compiles.”

Operational Impact

Maintenance. The package is mature and documented, with changelog, upgrade guide, and semantic-versioning intent. But only the current major receives fixes, so the team needs a recurring upgrade cadence and a watch on the repository move. Schema files become production code: they need review, ownership, versioning, and CI checks. Custom directives and scalars require PHP/Laravel expertise. Deploy runbooks must cover schema cache refresh, query cache invalidation, and persisted-query cache behavior.

Support. Support is community-driven through GitHub discussions/issues and a sponsorable maintainer. There is no implied commercial SLA. The TPM should either budget internal Laravel expertise, sponsor/contract support, or accept community-response risk. The repository transition should trigger a review of support channels, security disclosure routing, and release monitoring.

Scaling. The PHP application tier can scale horizontally, but GraphQL shifts pressure to query planning, database access, and cache correctness. Use pagination, eager loading, @lazyLoad, complexity/depth limits, and persisted queries. Schema and query caches reduce CPU but introduce stale-cache failure modes. Subscriptions add Redis and websocket fan-out capacity planning. The database remains the likely bottleneck; Lighthouse does not remove N+1 risk.

Failure modes. Watch for stale schema/query caches after deploy, broken custom directives, authorization gaps in @can/guard usage, N+1 queries and timeouts, partial writes in nested mutations, subscription fan-out failures, error leakage through GraphQL responses, and major-version upgrade breakage. Also treat the repository move as a supply-chain failure mode: verify package availability, advisory routing, and maintainer responsiveness before production commitment.

Ramp-up. Laravel engineers should become productive in one to two weeks for basic schema/directive work; deeper mastery of custom directives, scalars, subscriptions, performance tuning, and schema governance takes one to two months. Budget for GraphQL schema-design training, security review of directives, load testing, and a schema review board or designated owner. Track adoption with p95 latency, error rate, rejected query-complexity rate, cache hit ratio, schema-change lead time, N+1 findings, and consumer migration progress.