Graphiql Laravel Package

Getting Started

Install and reach the UI in three steps:

composer require noh4ck/graphiql
php artisan vendor:publish --provider="Noh4ck\GraphiQL\GraphiQLServiceProvider"
php artisan route:list | grep graphiql   # confirm the route is registered

On Laravel 5.5+ the service provider is auto-discovered; on 5.4 and below add Noh4ck\GraphiQL\GraphiQLServiceProvider::class to config/app.php.

First use case: you already have a Laravel GraphQL endpoint wired up (this package is only the UI — it does not implement GraphQL itself). The typical pairing is folklore/graphql (or rebing/graphql-laravel). Once that endpoint responds at /graphql, visit http://your-app.test/graphiql, and you get the classic GraphiQL IDE: schema introspection on the left, query editor in the middle, JSON results on the right.

Where to look first:

• config/graphiql.php after publishing — route path and middleware live here.
• The package's src/ route definition to confirm which GraphQL URL the UI points at (it is baked into the served view).
• php artisan route:list — the fastest sanity check that the UI is reachable.

If the page loads but queries fail, the problem is almost always the GraphQL endpoint, not this package.

Implementation Patterns

Environment-gated exposure (recommended). The UI is an unauthenticated debugging tool by default. Lock it down:

// config/graphiql.php
return [
    'route' => 'graphiql',
    'middleware' => ['web', 'auth'], // or restrict via env below
];

Or keep it dev-only with a service provider boot() guard:

public function boot()
{
    if (! app()->environment('local', 'staging')) {
        abort(404);
    }
}

Wrapping the route in auth is the simplest way to keep the IDE around on staging without leaking your schema to the public.

Pairing with your GraphQL layer. Point the IDE at whatever endpoint your backend exposes. With folklore/graphql the default is /graphql; with rebing/graphql-laravel it may be /graphql or a custom path depending on your config. If you changed the endpoint, you generally need to override the package's published view (see Gotchas) since the URL is set client-side in the GraphiQL <script>.

Day-to-day workflow. Treat it as your API scratchpad:

1. Introspect the schema (the docs pane updates automatically).
2. Paste mutations you're building; use the variables pane instead of string-interpolating inputs.
3. Copy working queries into feature tests / an docs/ folder — the IDE gives you no history, so persistence is on you.
4. Use query name headers (X-Request-Id-style) if your middleware logs requests.

Integration with feature tests. Don't test through the IDE route — test the underlying /graphql endpoint directly with Laravel's HTTP test client. The GraphiQL route is a UI convenience; asserting on it only verifies static HTML.

Replacing it when you upgrade. Because both this package and folklore/graphql are archived, plan the migration path now: lighthouse-php/lighthouse ships its own GraphiQL UI (/graphiql via its Playground/GraphiQL directives) and is actively maintained. That is the natural successor for any long-lived project.

Gotchas and Tips

• Archived = frozen. Last release April 2019. Expect breakage on Laravel 8+ (route registration, view namespace, and the bundled GraphiQL JS version are all pre-modern). Pin your framework version or budget for a fork.
• It is not a GraphQL server. A very common confusion: installing this package alone yields a UI that errors on every query until a GraphQL executor package is installed and configured. Error messages in the browser console ("Failed to fetch", 404 on POST) almost always mean the endpoint, not the package.
• CSRF on POST. GraphiQL issues POST requests. If the endpoint sits behind the web middleware group, CSRF will reject them. Ensure the GraphQL route is in the api group or explicitly CSRF-exempt; otherwise every query returns 419 and the UI looks broken.
• Route conflicts. If you already define a graphiql named route, or your GraphQL endpoint lives at the same path you configured, you'll get collisions. Check route:list first.
• Debugging order: (1) does /graphiql render? → route/middleware. (2) does the network tab show a POST? → endpoint URL in the view. (3) is the POST 419/401/404? → CSRF/auth/REST path. (4) does the JSON come back an errors array? → now it's a schema resolver issue, unrelated to this package.
• Overriding the view. Publish views (php artisan vendor:publish --tag=views where supported) rather than editing vendor/, so the endpoint URL and GraphiQL JS version can be patched locally. This is also your escape hatch if the bundled GraphiQL asset is too old for your browser.
• Middleware is per-route, not global. Setting 'middleware' => ['auth'] in the config affects only the IDE page, not the GraphQL endpoint it calls — lock both or neither.
• CORS. If you serve the IDE from one origin and the GraphQL endpoint from another (common in Docker setups), you need fruitcake/laravel-cors configured for the GraphQL route, or the browser will block the POST even though curl works.
• Extension point: the package is intentionally tiny — the only meaningful customization surfaces are the config file (route + middleware) and the published view (endpoint URL, GraphiQL version, custom headers). Anything beyond that, fork it or migrate to Lighthouse.