Lighthouse Laravel Package

Product Decisions This Supports

• API Modernization: Accelerate migration from REST to GraphQL for unified, flexible data fetching (e.g., replacing legacy endpoints with a single GraphQL schema).
• Developer Productivity: Reduce boilerplate by leveraging Laravel’s ecosystem (e.g., Eloquent models, validation) while adopting GraphQL’s declarative syntax.
• Roadmap Prioritization:
  • Build vs. Buy: Justify adopting Lighthouse over custom GraphQL implementations (e.g., webonyx/graphql-php) by highlighting its Laravel integration, built-in directives (@skip, @include), and tooling (e.g., schema stitching, file uploads).
  • Feature Flags: Use client directives (e.g., @skip) to roll out experimental features to subsets of users without schema changes.
• Use Cases:
  • Headless CMS/Backend for Frontend (BFF): Serve tailored GraphQL APIs to mobile/web apps (e.g., conditional fields via @include).
  • File Handling: Enable file uploads (e.g., user avatars, document attachments) via multipart requests without reinventing middleware.
  • Deprecation Management: Phase out legacy fields/enums with deprecation warnings and automated usage tracking.

When to Consider This Package

• Adopt if:
  • Your team is already using Laravel and needs GraphQL with minimal context-switching (e.g., shared auth, Eloquent models).
  • You require client-side flexibility (e.g., conditional queries via @skip/@include) without server-side logic changes.
  • File uploads or multipart requests are a priority (e.g., media-heavy apps).
  • You need schema extensibility (e.g., dynamic SDL injection, stitching) without PHP-native type definitions.
• Look elsewhere if:
  • You’re not using Laravel (Lighthouse’s integration assumes Laravel’s service container, events, and middleware).
  • You need real-time subscriptions (Lighthouse lacks built-in support; consider realtime-lighthouse or graphql-ws).
  • Your use case demands complex native PHP types (e.g., recursive types) where SDL feels limiting.
  • You require enterprise-grade tooling (e.g., GraphQL Playground/IDE integrations) beyond Lighthouse’s core focus.

How to Pitch It (Stakeholders)

For Executives: "Lighthouse lets us unify our APIs under GraphQL—reducing frontend complexity and backend duplication—while leveraging Laravel’s strengths. It’s like REST’s successor: one endpoint for all data needs, with built-in features for phased rollouts (e.g., @skip for A/B testing) and file handling. The MIT license and active community (3.5K stars) mean low risk, and it integrates seamlessly with our existing stack."

For Engineering: *"Lighthouse turns Laravel into a GraphQL powerhouse with zero trade-offs:

• Zero Boilerplate: Resolvers map 1:1 to Eloquent models or services.
• Client Control: @skip/@include directives let clients optimize queries without server changes.
• File Uploads: Multipart support out of the box (no custom middleware).
• Schema Agility: Stitch schemas dynamically or inject SDL at runtime.
• Deprecation Safety: Track usage of deprecated fields before removal. It’s the fastest path to GraphQL for Laravel teams—no reinventing the wheel."*

For Developers: *"Say goodbye to REST over-fetching. Lighthouse lets you:

• Define schemas in .graphql files (or stitch them dynamically).
• Use Laravel’s validation/eloquent directly in resolvers.
• Skip fields conditionally: @skip(if: $isAdmin).
• Upload files with a single scalar type. Plus, it’s battle-tested (used by [list of sponsors]) and backed by the Laravel community."