⚡ Cache the schema on every environment that runs without debug

[Mir-Zairan]

The compiler pass only puts the schema factory in prod mode when the environment is literally named prod. Call it staging, preprod, uat or qa and it falls through to the factory default, dev mode, which checks every controller and type file for changes on every request.

Nothing reports this, so it is easy to run for years without noticing. We found it chasing a slow page on staging: 1.8s per GraphQL call, 0.12s once the schema was cached, with the database work taking milliseconds either way.

Checking files for changes is what kernel.debug means in Symfony, so that drives it now instead of the environment name.

The second commit adds schema.auto_reload for the environments that do not fit that rule, defaulting to '%kernel.debug%' the way Twig's own auto_reload does. A staging server running with debug on can keep the cache, and a debug-off setup can keep picking up edits.

Two behaviour changes for the release notes. An environment with debug off and a name other than prod now caches the schema, and prod with debug on now reloads it.

The README has a "Schema caching" section: the default, what each setting changes, an override example, and that a debug-off deploy has to clear the cache when a controller or type changes.

Tests cover staging with debug off, prod with debug on, and both explicit overrides, checking that the other mode is not configured. The test kernel hardcoded debug on and the test environment, so it takes both now, and gets its own cache directory when debug is off, otherwise it would reuse a dumped container and hide changes to the pass.

[Mir-Zairan]

@enricobono @Lappihuan @andrew-demb Kindly review the pr.

[andrew-demb]

Thank you for the proposal. Let me share my throughts on the topic.

I think using kernel.debug as the default is the right direction, but it would be useful to keep schema reloading independently configurable.

Could we expose an option like this?

graphqlite:
    schema:
        auto_reload: '%kernel.debug%'

This would preserve the proposed behavior by default while allowing applications to override it - for example, staging with debug enabled but schema caching retained, or a debug-off development environment that should still detect schema changes.

auto_reload should mean that cached controller/type metadata is validated against source-file changes. Caching remains enabled in both modes; when disabled, cached schema metadata is trusted until the GraphQLite cache is cleared.

Please also update the README to document:

• the default relationship with kernel.debug;
• what enabling and disabling schema.auto_reload actually changes;
• an override example;
• that debug-off deployments must clear the GraphQLite cache after schema-related code changes.

The tests should cover at least staging + debug=false and prod + debug=true, including explicit overrides, and verify that only the expected factory mode is configured.

[Mir-Zairan]

Thank you for the proposal. Let me share my throughts on the topic.

I think using kernel.debug as the default is the right direction, but it would be useful to keep schema reloading independently configurable.

Could we expose an option like this?

graphqlite:
    schema:
        auto_reload: '%kernel.debug%'

This would preserve the proposed behavior by default while allowing applications to override it - for example, staging with debug enabled but schema caching retained, or a debug-off development environment that should still detect schema changes.

auto_reload should mean that cached controller/type metadata is validated against source-file changes. Caching remains enabled in both modes; when disabled, cached schema metadata is trusted until the GraphQLite cache is cleared.

Please also update the README to document:

• the default relationship with kernel.debug;
• what enabling and disabling schema.auto_reload actually changes;
• an override example;
• that debug-off deployments must clear the GraphQLite cache after schema-related code changes.

The tests should cover at least staging + debug=false and prod + debug=true, including explicit overrides, and verify that only the expected factory mode is configured.

Done. Added schema.auto_reload defaulting to '%kernel.debug%', following the same shape as Twig's own auto_reload. The README has a Schema caching section covering the default, what each setting changes, an override example, and clearing the cache on debug-off deploys. Tests cover staging with debug off, prod with debug on, and both explicit overrides, asserting the other mode is not configured. Thanks for your valuable suggestion!