Lumina Laravel Package

Getting Started

Lumina is a Symfony-first GraphQL engine, not a Laravel package. Before you invest a day, confirm two things:

1. composer show netmex/lumina — inspect its require block. If it pulls symfony/http-kernel, symfony/security-*, and expects ValueResolverInterface, you are integrating a Symfony bundle into a Laravel app, not installing a Laravel package.
2. Decide whether you actually need this over Lighthouse (Laravel-native, Eloquent-aware, Blade-style SDL directives). Lumina only makes sense if you are running a hybrid Symfony/Laravel stack, or you specifically want Lumina's directive set and are willing to write the glue.

Minimal steps:

composer require netmex/lumina

Then:

• Read the README sections on schema organization and directives first — that is where the package's opinions live. Skip the marketing bullet list.
• Create the recommended schema layout (schema/types, schema/queries, schema/mutations or whatever the README prescribes) rather than one giant schema.graphql.
• Register a single Laravel route that hands the request to Lumina's executor, since Laravel has no autodiscovery for Symfony bundles:

// routes/api.php
Route::post('/graphql', GraphQLController::class);

• Wire the engine by hand in a service provider: bind the schema loader, the directive registry, and (importantly) an adapter that resolves arguments in place of Symfony's ValueResolverInterface.

First use case: a single read-only query over one model with a @hasMany relation and pagination. Do not start with mutations or authorization — those are where the Symfony/Laravel impedance mismatch bites hardest.

Implementation Patterns

Schema-first, one file per type. The release notes explicitly recommend schema organization; follow it. Keep directives in SDL where reviewers can see them, not hidden in PHP attributes. This also makes diffs reviewable when you upgrade Lumina.

Directive composition. Lumina's value is the directive set (@hasMany, @belongsTo, filtering, sorting, pagination, aggregation). The idiomatic pattern is stacking them on a field:

type User {
  posts(
    filter: _ @filter
    orderBy: _ @sort
    first: Int! @paginate(defaultCount: 20)
  ): [Post!]! @hasMany
}

Treat this as your primary lever — you get a lot of query surface for free, which is exactly why the authorization and N+1 sections below matter.

Authorization must be adapted, not assumed. @can, @role, and @owner almost certainly resolve against Symfony's security voters, not Laravel's Gate. Plan on writing an adapter so @can(ability: "update") calls Gate::allows('update', $model). Centralize this in one directive implementation and reuse it — do not scatter $user->can() calls into resolvers.

Mutations with input validation. Use Lumina's argument/input validation rather than Laravel FormRequests. You lose authorize() and passedValidation(), so keep validation rules in a shared class both Lumina and any REST endpoints can consume.

Relations and batching. @hasMany/@belongsTo are convenient but are the classic N+1 trap. Prefer an explicit eager-load strategy — either configure Lumina's batching if the README documents it, or resolve relations yourself with with()/load() and expose them as plain fields. Benchmark a list query with 50 parents before shipping.

Wrap the HTTP boundary once. One controller, one request/response mapping. Let Lumina own schema execution; let Laravel own middleware, auth, rate limiting, and error formatting. Do not let Lumina's exception handling leak Symfony-flavored error payloads to a Laravel frontend.

Aggregation for dashboards. The aggregation directive is the fastest way to build admin/reporting queries. Keep these on a separate schema endpoint or role-gate them — see gotchas.

Gotchas and Tips

• The package targets Symfony. ValueResolverInterface is Symfony HttpKernel. Laravel does not have it. You will write a resolver layer that inspects GraphQL arguments and injects models, or you will abandon Lumina for Lighthouse. Budget for this; it is not a five-minute install.
• @can, @role, @owner do not know about Laravel Gates, Policies, or Spatie permissions. If you assume they do, you ship an API where every authorization check silently passes or fails closed in ways your tests do not cover. Write one explicit test per directive.
• Beware silent authorization bypass. Directive-based auth is easy to forget on a new field. Add a CI check or a schema test that asserts every mutation field carries at least one auth directive.
• Aggregation directives are a DoS surface. count, sum, avg over a joined filter can scan enormous tables. Enforce limits, disable aggregation on public schemas, and cache dashboards aggressively.
• v1.0.0 is a first stable release. Expect directive signatures and schema conventions to shift in 1.x minors. Pin the version ("netmex/lumina": "1.0.*") and read each changelog before upgrading — there is no migration guide yet.
• Error semantics. GraphQL returns HTTP 200 with an errors array. Laravel's exception handler and frontend clients expecting 4xx/5xx will be confused. Normalize in your controller and log the underlying exception, because Lumina may mask it as a generic GraphQL error.
• Cache the parsed schema in production. Recompiling SDL per request is expensive; do it on deploy, keyed by a hash of your schema files, the same way you cache config and routes.
• Disable introspection in production. Nothing in the release notes says it is on by default, and a public introspection endpoint leaks your entire authorization model.
• No Laravel service provider is mentioned. No auto-discovery, no publishable config, no facade. Assume manual wiring and write your own LuminaServiceProvider.
• Debugging tip: stand up GraphiQL or Altair against the local endpoint. Directive problems are almost always visible in the schema (/graphql introspection) before they are visible in PHP. Dump the compiled schema when a directive appears to be ignored — a mis-registered directive fails quietly.
• Extension points to lean on: custom directive classes, custom type resolvers, and custom validation rules. If you need Laravel-specific behavior, implement it as a directive rather than forking the package — that keeps you upgradable through the likely 1.x churn.

Recommendation: for a purely Laravel codebase, default to Lighthouse and use Lumina only when you have a concrete Symfony dependency or a specific need for its directive semantics. If you do adopt Lumina, treat the Symfony/Laravel bridge as a first-class piece of your codebase with its own tests.