Weave Code
Lighthouse Laravel Package
nuwave/lighthouse
Lighthouse is a GraphQL framework for Laravel that combines the best ideas of both ecosystems. It solves common tasks with ease and offers flexibility when you need it. Full documentation is available at lighthouse-php.com.
A framework for serving GraphQL from Laravel
Frequently asked questions about Lighthouse
- How do I install Lighthouse in a Laravel application?
- Install Lighthouse as a Composer dependency, publish its configuration, and add a GraphQL schema file under the graphql directory. Then expose a route for the GraphQL endpoint, typically /graphql, and run the schema cache command as part of deployment. Lighthouse runs on your existing PHP-FPM or Octane workers, so no separate GraphQL service is required.
- Does Lighthouse run as a separate GraphQL server?
- No. Lighthouse runs inside the Laravel application process and serves GraphQL from the same PHP-FPM or Octane workers and database connections you already operate. That lets resolvers reuse Eloquent models, policies and gates, form requests, cache stores and broadcasting without a data-sync layer. The trade-off is that the GraphQL tier is coupled to Laravel rather than being language-agnostic.
- Which Laravel and PHP versions does Lighthouse support?
- The exact Laravel and PHP versions depend on the Lighthouse major you pin, and Lighthouse tracks Laravel majors closely. Only the current Lighthouse major receives new features and bug fixes, so check the version-specific documentation and upgrade guide before choosing a release. Plan Laravel upgrades as a coordinated Lighthouse and Laravel upgrade rather than a routine single-package chore.
- Is Lighthouse schema-first or code-first?
- Lighthouse is schema-first: your GraphQL schema is the contract, and behavior is declared with directives such as @all, @paginate, @find, @create, @update, @delete, @field, @guard, @can and @whereConditions. A large share of API logic lives in .graphql files rather than PHP controllers, so schema files need the same code review, ownership and security review. It is a poor fit if your team wants code-first schema generation from PHP attributes.
- How do I cache the Lighthouse GraphQL schema in production?
- Run php artisan lighthouse:cache at deploy time so Lighthouse does not parse the schema on every request. Cache v2, which uses a PHP file plus OPcache, should be enabled deliberately for production. If you skip this step you get per-request schema parsing and a stale-cache failure mode after deploys.
- How do I test Lighthouse GraphQL endpoints in Laravel?
- Lighthouse provides testing helpers such as MakesGraphQLRequests, assertGraphQLErrorMessage, assertGraphQLValidationError, rethrowGraphQLErrors and the ClearsSchemaCache trait. These make end-to-end coverage in CI achievable early in adoption. Use them to assert both successful queries and authorization or validation failures, especially on nested fields.
- How do I handle authentication and authorization in Lighthouse?
- Use directives such as @guard and @can to express authentication and authorization in the schema. Authorization is easy to omit on a nested field, and the failure is silent because data is returned instead of an error. Field-level authorization must be explicit and tested per node, with schema security review treated as seriously as controller review.
- Can Lighthouse reuse Eloquent models, policies and validation?
- Yes. Lighthouse resolvers and directives such as @all, @paginate, @find, @create, @update, @delete and @field can reuse existing Eloquent models, policies and gates, form requests, Scout indexes, cache stores and broadcasting. Directives like @whereConditions, @orderBy, @validator, @spread, @cache, @throttle and @complexity cover common filtering, sorting, validation, caching, rate limiting and complexity concerns. This reuse is the main reason to run Lighthouse inside Laravel instead of a separate GraphQL service.
- What are alternatives to Lighthouse for GraphQL in Laravel?
- Lighthouse is a strong fit when your backend is Laravel and you want a typed, aggregated GraphQL API that reuses your existing domain logic. If you want code-first schema generation from PHP attributes, are standardizing on OpenAPI and REST tooling, or need a language-agnostic GraphQL tier, a standalone Node or Go GraphQL server is a better boundary. Evaluate those alternatives against your team's schema governance and operational model, not just feature lists.
- Is Lighthouse still maintained after the move to spawnia/lighthouse?
- The README states the project is planned to move from nuwave/lighthouse to spawnia/lighthouse, so the current major is maintained but the repository governance and package identity may change. A move can affect the Composer package name, Packagist entry, security-advisory feeds, internal dependency allowlists, SBOM entries and documentation links. Budget a re-verification task and keep CVE monitoring updated, and confirm the current major and its support status before pinning.
Weaver
How can I help you explore Laravel packages today?