Lighthouse Laravel Package

Product Decisions This Supports

• API Modernization: Accelerate migration from REST to GraphQL for unified, flexible, and scalable API consumption. Lighthouse enables incremental adoption by leveraging existing Laravel models and Eloquent relationships.
• Developer Productivity: Reduce boilerplate for GraphQL schema definition and resolver logic. Directives like @bind, @hasOneThrough, and @paginate automate common patterns (e.g., route model binding, complex relationships, pagination).
• Roadmap Prioritization:
  • Build vs. Buy: Avoid reinventing GraphQL infrastructure (schema stitching, subscriptions, validation) by adopting Lighthouse’s battle-tested directives and Laravel integration.
  • Feature Flags: Use @show/@hide directives to toggle GraphQL features (e.g., beta endpoints) without schema changes or client updates.
  • Performance Optimization: Prioritize features like Automatic Persisted Queries, file-based query caching, and lazy schema loading to reduce latency and server load.
• Use Cases:
  • Headless CMS: Dynamically expose Eloquent models as GraphQL types with fine-grained authorization via @can directives.
  • Real-Time Dashboards: Subscriptions with Laravel Reverb support for WebSocket-based updates.
  • Multi-Tenant SaaS: Isolate schemas or data via directives like @withoutGlobalScopes or custom middleware.
  • Bulk Operations: @createMany/@updateMany for efficient batch mutations (e.g., import tools, admin panels).

When to Consider This Package

Adopt Lighthouse If:

• Your stack is Laravel-centric: Deep integration with Eloquent, Laravel’s service container, and Artisan commands minimizes context-switching.
• You need GraphQL without complexity: Directives handle 80% of use cases (CRUD, relationships, auth, pagination) declaratively. Avoid over-engineering for simple APIs.
• Performance matters: Features like persisted queries, OPcache-optimized schema caching, and lazy loading reduce overhead for high-traffic APIs.
• You require real-time features: Native support for subscriptions (with Redis/Pusher/Reverb) and async mutations for background processing.
• Your team values Laravel’s ecosystem: IDE helpers, IDE-aware schema generation, and seamless testing (PHPUnit 12 support) improve developer experience.

Look Elsewhere If:

• You’re polyglot: Lighthouse is PHP/Laravel-specific. For multi-language backends, consider Apollo Server, Hasura, or GraphQL Yoga.
• You need schema stitching/federation: While Lighthouse supports federated tracing, advanced federation (e.g., Apollo Federation) requires additional tooling.
• Your use case is non-relational: Lighthouse excels with Eloquent. For NoSQL or custom data sources, pair with GraphQL PHP or build resolvers manually.
• You prioritize raw flexibility: Lighthouse’s directives abstract away low-level GraphQL control. For custom query parsing or experimental features, a lighter framework (e.g., graphql-php/graphql) may suit better.
• Lumen support is critical: Lighthouse deprecated Lumen support in v6.62.0. Use alternatives like graphql-php if targeting Lumen.

How to Pitch It (Stakeholders)

For Executives:

"Lighthouse lets us ship GraphQL APIs 10x faster by turning Laravel models into GraphQL endpoints with zero boilerplate. It’s like REST for the modern web—flexible, performant, and built for scale. Key wins:

• Unify APIs: Replace fragmented REST endpoints with a single GraphQL layer, reducing client-side complexity.
• Accelerate development: Directives like @paginate and @bind cut resolver code by 70%, letting teams focus on business logic.
• Future-proof: Supports real-time features (subscriptions), bulk operations, and feature flags—all without rewriting the backend.
• Proven: Used by companies like Spatie and backed by a mature Laravel ecosystem. MIT-licensed, no vendor lock-in."*

Ask: "Should we prioritize GraphQL for [X use case], or explore alternatives like REST+JSON:API?"

For Engineering Leaders:

"Lighthouse is the sweet spot between GraphQL frameworks—it’s not a monolith like Hasura, nor a low-level library like graphql-php. Here’s why it’s a slam dunk for our Laravel stack:

• Laravel-native: No context-switching. Use Eloquent models, Laravel middleware, and Artisan commands seamlessly.
• Directive-driven: Solve 90% of use cases with @hasOne, @paginate, @can, etc. Example:

  type User @model {
    posts @hasMany {
      title
      comments @hasMany {
        text
      }
    }
  }
  

• Performance optimizations:
  • Persisted queries reduce parsing overhead by 40%.
  • File-based caching leverages OPcache for near-instant schema loads.
  • Lazy schema validation defers expensive checks until queries are executed.
• Real-time ready: Subscriptions work out-of-the-box with Redis/Pusher/Reverb.
• Tooling: IDE helpers, PHPUnit integration, and lighthouse:print-schema for documentation.

Trade-offs:

• Not ideal for non-Laravel stacks or advanced federation needs.
• Directives abstract some GraphQL control (e.g., custom query parsing).

Recommendation: Start with Lighthouse for MVP, then extend with custom resolvers or middleware as needed."*

Ask: "Should we allocate [X] dev weeks to prototype Lighthouse vs. a custom GraphQL solution?"

For Developers:

"Lighthouse turns this:

// REST Controller
public function showPost(Post $post) {
    return response()->json($post->load('comments'));
}

Into this:

# Schema
type Post @model {
  id: ID!
  title: String!
  comments @hasMany { text: String }
}

# Query
query {
  post(id: 1) {
    title
    comments { text }
  }
}

Why it’s awesome:

• No resolvers: Directives like @model auto-generate queries/relationships.
• Laravel integrations:
  • Use @bind for route model binding (e.g., post(id: $id) → Post::findOrFail($id)).
  • @can for auth: posts @can(delete) { ... }.
• Performance: Persisted queries + caching = faster than REST for complex clients.
• Subscriptions: Real-time updates with minimal setup:

  subscription {
    postCreated {
      id
      title
    }
  }
  

Getting started:

1. Install: composer require nuwave/lighthouse.
2. Add @model to your Eloquent classes.
3. Profit.

Docs: lighthouse-php.com (active community, great IDE support)."*