Lighthouse Laravel Package

Technical Evaluation

Architecture Fit

• Schema-First GraphQL Integration: Lighthouse aligns perfectly with Laravel’s existing architecture by leveraging schema-first GraphQL (via .graphql files) while maintaining Laravel’s Eloquent ORM and service container. This avoids reinventing the wheel for GraphQL resolvers, reducing boilerplate and improving maintainability.
• Directive-Driven Development: The framework’s directive-based approach (e.g., @query, @mutation, @relation) maps cleanly to Laravel’s conventions (e.g., Eloquent models, relationships). This reduces cognitive load for backend developers familiar with Laravel.
• Modularity: Lighthouse’s plugin-like directives (e.g., @auth, @can, @paginate) allow incremental adoption. Teams can start with core CRUD and layer on features (e.g., subscriptions, federation) as needed.
• Laravel Ecosystem Synergy:
  • Authentication: Seamless integration with Laravel’s built-in auth (e.g., @auth directive uses Laravel’s Auth facade).
  • Validation: Leverages Laravel’s Form Requests and Validator for input validation.
  • Testing: Built-in support for Laravel’s Pest and PHPUnit (e.g., MocksResolvers).
  • Caching: Integrates with Laravel’s cache drivers (e.g., schema caching, persisted queries).

Integration Feasibility

• Low Friction for Laravel Teams:
  • No need to learn a new ORM or resolver pattern; resolvers are auto-generated from Laravel models/relationships.
  • Zero-config for basic CRUD (e.g., @query on a model auto-generates a resolver).
  • IDE Support: Generates _lighthouse_ide_helper.php for autocompletion in PHPStorm/PhpStorm.
• Backward Compatibility:
  • Supports Laravel 10–13 (as of v6.66.0) with minor version stability (no breaking changes between minor updates).
  • Deprecation Policy: Clear migration paths for major versions (e.g., Lumen support deprecated in v6.62.0).
• Performance Optimizations:
  • Schema Caching: File-based and OPcache-optimized (ASTCache).
  • Persisted Queries: Reduces parsing overhead (supports hybrid cache modes).
  • Lazy Loading: @lazyLoad directive defers expensive queries until needed.
  • Query Complexity: Built-in complexity analysis to prevent costly queries (e.g., @paginate with complexityResolver).

Technical Risk

• Migration to Spawnia:
  • Repository Move: The package is planned to migrate to spawnia/lighthouse (see README). This introduces vendor risk if the migration disrupts dependencies or documentation.
  • Mitigation: Monitor the discussion thread and plan for a parallel testing phase post-migration.
• Learning Curve for Advanced Features:
  • Directives: While simple directives (e.g., @query) are intuitive, advanced features (e.g., @federation, @bind, @hasOneThrough) may require deeper GraphQL knowledge.
  • Custom Resolvers: Teams extending beyond auto-generated resolvers must understand Lighthouse’s resolver lifecycle and directive hooks.
• Subscription Complexity:
  • Real-time Features: Subscriptions (via Laravel Echo/Pusher/Reverb) add complexity. Teams must configure broadcast drivers and handle channel authorization.
  • Error Handling: Async mutations/subscriptions require robust error reporting (e.g., ReportingErrorHandler).
• Schema Evolution:
  • Breaking Changes: Major version upgrades may require schema adjustments (e.g., deprecating @hide in favor of @feature).
  • Tooling Dependency: Relies on graphql-php and webonyx/graphql-php, which may introduce version conflicts.

Key Questions

1. Adoption Strategy:
   • Should we adopt Lighthouse incrementally (start with CRUD) or all-in (full GraphQL API)?
   • How will we train developers on directives vs. custom resolvers?
2. Performance:
   • Will persisted queries and schema caching meet our expected QPS? (Benchmark with production-like loads.)
   • How will we handle query complexity for nested/malicious queries? (E.g., @depthLimit directive.)
3. Observability:
   • Are the built-in reporting tools (e.g., reports.proto, BuildExtensionsResponse) sufficient, or do we need custom logging?
   • How will we monitor subscription health (e.g., channel leaks, latency)?
4. Security:
   • How will we enforce rate limiting (e.g., @throttle directive) and authz (e.g., @can) at scale?
   • Are client-safe errors (configurable via ReportingErrorHandler) adequate for our error disclosure policy?
5. Future-Proofing:
   • How will we handle the repository migration to spawnia/lighthouse? (E.g., dependency updates, CI/CD adjustments.)
   • Does Lighthouse support our long-term Laravel version (e.g., Laravel 14+)? (Check upgrade guides.)
6. Tooling:
   • Will we use GraphQL Playground/Apollo Studio for dev, or build custom tooling?
   • How will we version our GraphQL schema alongside Laravel releases?

Integration Approach

Stack Fit

• Laravel-Centric Design:
  • Eloquent ORM: Lighthouse resolvers mirror Eloquent models/relationships, enabling teams to reuse existing business logic.
  • Service Container: Directives and resolvers are container-bound, allowing dependency injection (e.g., repositories, services).
  • Middleware: Supports Laravel’s middleware pipeline for GraphQL requests (e.g., @middleware directive).
• GraphQL Ecosystem:
  • Schema Registry: .graphql files are version-controlled alongside Laravel code (unlike code-first approaches).
  • Tooling: Integrates with GraphQL IDE helpers, validation, and federation (e.g., @key, @extends).
• Real-Time Extensions:
  • Subscriptions: Works with Laravel Echo, Pusher, or Reverb (added in v6.47.0).
  • WebSockets: Supports Laravel’s broadcasting for scalable pub/sub.

Migration Path

1. Phase 1: Proof of Concept (PoC)

   • Goal: Validate Lighthouse’s fit for a single domain (e.g., Users module).
   • Steps:
     • Install Lighthouse (composer require nuwave/lighthouse).
     • Define a basic schema (e.g., User.graphql with @query, @mutation).
     • Test CRUD operations via GraphQL Playground.
     • Benchmark performance (e.g., resolver latency, schema cache hits).
   • Success Metrics: Zero major blockers, <10% manual resolver code.

2. Phase 2: Incremental Rollout

   • Goal: Replace REST/gRPC endpoints for non-critical features.
   • Steps:
     • Migrate read-heavy endpoints first (e.g., @query for lists).
     • Add validation (Laravel Form Requests) and authz (@can).
     • Implement pagination (@paginate) and lazy loading (@lazyLoad).
     • Deprecate legacy endpoints with API gateways (e.g., Kong, Laravel Gateway).
   • Success Metrics: 30% of API traffic via GraphQL, <5% error rate.

3. Phase 3: Full Adoption

   • Goal: Full GraphQL API with real-time and federation features.
   • Steps:
     • Add subscriptions (e.g., @subscription for notifications).
     • Implement federation (if needed) with @key, @entity, @extends.
     • Migrate write-heavy endpoints (e.g., @mutation for orders).
     • Set up persisted queries and query complexity limits.
   • Success Metrics: 90% of API traffic via GraphQL, <1% latency regression.

Compatibility

• Laravel Versions:
  • Supported: 10–13 (as of v6.66.0). Test compatibility with Laravel 14 early.
  • Deprecated: Lumen support removed in v6.62.0 (not a concern for most teams).
• PHP Versions:
  • Requires PHP 8.1+ (check composer.json constraints).
  • PHPUnit 12 support added in v6.64