Graphiql Bundle Laravel Package

Getting Started

Install it as a dev-only dependency so it never ships to production:

composer require --dev overblog/graphiql-bundle

If you use Symfony Flex, accept the contrib recipe. It normally registers the bundle only for dev/test in config/bundles.php:

Overblog\GraphiQLBundle\OverblogGraphiQLBundle::class => ['dev' => true, 'test' => true],

Without Flex, add that line manually and load the bundle's routes only in the dev environment (e.g. config/routes/dev/overblog_graphiql.yaml).

The first thing to check is which GraphQL endpoint your app already exposes:

php bin/console debug:router | grep -i graphql
php bin/console config:dump-reference overblog_graphiql

Then add a minimal configuration in config/packages/dev/overblog_graphiql.yaml:

overblog_graphiql:
    graphql_endpoint: '/graphql'
    graphiql:
        path: '/graphiql'

Clear the cache and open /graphiql in your browser. Your first use case is almost always the same: confirm the schema is reachable, browse the documentation panel, run a simple query with variables, and test mutations against your dev data before wiring them into the frontend. If the UI loads but queries fail, open the browser Network tab and check what URL GraphiQL is posting to — endpoint mismatches are the most common first-run problem.

Implementation Patterns

Keep configuration environment-scoped. Put the config in config/packages/dev/overblog_graphiql.yaml and routes in config/routes/dev/. A production deployment should not be able to reach the UI even accidentally. If you need it in staging, create a dedicated config file with an explicit security rule.

Use default headers for local authentication. GraphiQL runs in the browser, so cookie/session auth works automatically. For token-based APIs, inject a dev token from an environment variable rather than committing it:

overblog_graphiql:
    graphql_endpoint: '%env(GRAPHQL_ENDPOINT)%'
    graphiql:
        path: '/graphiql'
        default_headers:
            Authorization: 'Bearer %env(GRAPHQL_DEV_TOKEN)%'
        default_query: |
            query Ping { __typename }

This lets you exercise protected queries and mutations from the UI without manually pasting a token on every reload.

Match the fetcher to your server. When you use overblog/graphql-bundle, the native GraphQL fetcher is the natural choice. If your GraphQL endpoint is provided by another library or an external service, use the generic fetch-based fetcher and point graphql_endpoint at that URL. Confirm the selected mode in config:dump-reference overblog_graphiql for your installed version.

Handle multiple schemas or endpoints with separate paths. If your app exposes more than one schema (for example through overblog/graphql-bundle's multi-schema routing), give each one its own GraphiQL path and endpoint URL. Check the generated route names with debug:router rather than guessing:

overblog_graphiql:
    graphql_endpoint: '/graphql/public'
    graphiql:
        path: '/graphiql/public'

Repeat for the admin/internal schema with a different path and, ideally, a different security rule.

Make it part of your mutation workflow. GraphiQL is most valuable when you use the variables panel and named operations consistently. Save a canonical "smoke test" query in default_query and keep a shared collection of example variables in your team docs. This turns GraphiQL into a lightweight manual test harness for new mutations before they are covered by integration tests.

Pair it with symfony serve and browser dev tools. Run the app locally, keep the Network tab open, and inspect the actual GraphQL request payload and response. This is faster than adding temporary logging when debugging validation errors, serialization issues, or authorization failures.

Gotchas and Tips

A dev dependency must be dev-registered. If overblog/graphiql-bundle is in require-dev but the bundle is registered unconditionally in config/bundles.php, a production build with composer install --no-dev will fail because the bundle class is missing. Always scope the bundle entry to ['dev' => true, 'test' => true] and keep its routes out of production route loading.

Never expose GraphiQL publicly. Even if the GraphQL endpoint is public, the UI is a developer tool. Add an access_control rule for the dev path, restrict by IP at the web server level, or omit the route entirely in production. Also verify that introspection is disabled where appropriate; GraphiQL's documentation and autocomplete rely on introspection, so a disabled schema will look broken in the UI.

CDN assets can break in restricted environments. The rendered page typically pulls GraphiQL/React assets from a CDN. Behind a corporate firewall, in an air-gapped environment, or under a strict Content-Security-Policy, the page may load blank. Check the browser console for blocked requests and either relax the CSP for the dev path or host the assets locally if your version of the bundle supports it.

Endpoint and CORS mismatches look like GraphQL errors. If GraphiQL is served from a different origin than the GraphQL endpoint, the browser will block the request. A 401/403 usually means Symfony security intercepted the request before GraphQL ran, not that your query is wrong. Inspect the response status and body in the Network tab first.

Clear the cache after configuration changes. Route and container configuration is cached. After editing the bundle config or moving route files, run bin/console cache:clear and, if routes look stale, bin/console debug:router again.

Subscriptions are not supported out of the box. GraphiQL's standard transport handles queries and mutations; WebSocket subscriptions require additional client configuration that this bundle does not provide by default. Use a dedicated client or a standalone GraphQL IDE if subscriptions are central to your workflow.

For template customisation, use standard Symfony overrides. If you need to adjust the rendered page, check the bundle's Resources/views directory and override the template under templates/bundles/OverblogGraphiQLBundle/. Confirm the exact template path in your installed version rather than assuming it from the README.

Know when to reach for a different IDE. This bundle is intentionally thin and its GraphiQL UI follows the bundled frontend version. If your team depends on tabs, persisted queries, environment switching, or plugin ecosystems, a standalone tool such as Altair or a newer GraphiQL deployment may be a better daily driver while keeping this bundle as the zero-setup default.