reference.php #62588

floxblah · 2025-12-01T09:45:25Z

floxblah
Dec 1, 2025

Hi there,

I have a question about the auto-generated reference.php file that was introduced in recent Symfony versions (generated by PhpConfigReferenceDumpPass).

This file is automatically regenerated every time I run php bin/console cache:clear
It's generated in the config directory (which is typically versioned)
.

What's the goal of this file ?
Is this file intended to be committed to version control, or should it be gitignored?

Answered by GromNaN

Dec 1, 2025

This file provides array-shape type for the PHP configuration. It should be committed with your code and might change when you update the composer dependencies.

See: https://symfony.com/blog/new-in-symfony-7-4-better-php-configuration

These shapes are generated dynamically based on the bundles installed in your application. The generated file is called reference.php and is stored in the config/ directory. You should commit it to your repository and optionally add a new entry in the autoload section of composer.json (for example, "classmap": ["config/"]).

View full answer

GromNaN · 2025-12-01T09:59:09Z

GromNaN
Dec 1, 2025
Collaborator

This file provides array-shape type for the PHP configuration. It should be committed with your code and might change when you update the composer dependencies.

See: https://symfony.com/blog/new-in-symfony-7-4-better-php-configuration

These shapes are generated dynamically based on the bundles installed in your application. The generated file is called reference.php and is stored in the config/ directory. You should commit it to your repository and optionally add a new entry in the autoload section of composer.json (for example, "classmap": ["config/"]).

0 replies

parijke · 2026-02-02T18:30:48Z

parijke
Feb 2, 2026

Does this file work fine in a shared kernel multi app? Since we have 5 APP_ID's. We experience bootstrapping issues when switchings apps.

5 replies

parijke Feb 6, 2026

We have currently solved it with this in our Kernel.php (thx @Ilyes512 ) but we are not sure if we experince problems in the future. The reference.php interferes the freshness check in shared kernel app

    #[Override]
    protected function getKernelParameters(): array
    {
        $parameters = $this->getKernelParametersTrait();

        $parameters['kernel.application_id'] = $this->getApplicationId()->value;
        $parameters['kernel.tenant_id'] = $this->getTenantId()->value;

        // Should only be used by PhpConfigReferenceDumpPass to generate the config reference for the app config dir
        // parameter.
        $parameters['.kernel.config_dir'] = $this->getBuildDir();

        return $parameters;
    }
    ```

GromNaN Feb 6, 2026
Collaborator

This file only depends on the bundles that are enabled in your dev environment.

parijke Feb 6, 2026

Yes, which are different ones per apps, so the file constantly changes after swithcing apps, causing cache invalidation issues (in dev mode)

Ilyes512 Feb 6, 2026

The above snippet is not really a fix it's more of a workaround since the files now land in de build dir wish is inside the var dir assuming default config. Both my editor and the static code tool won't parse the file.

Being able to just turn this feature off would be even better.

This file only depends on the bundles that are enabled in your dev environment.

We are using a Shared Kernel setup where depending on an env var the loaded config, bundles etc are different. And so yes, that would mean a different reference file depending on the current shared kernel being loaded.

okorneliuk Mar 23, 2026

With reference.php per app, we will have copied definitions for shared bundles in each reference.php file. IMO we should have the ability to configure shared reference.php for shared bundles and app-specific reference.php for app-specific bundles. However, at the moment of creation reference.php, we don't know which bundles are shared and which are app-specific, because in the shared kernel config, all bundles are merged into one flat array.

Justinas-Jurciukonis · 2026-03-12T16:24:30Z

Justinas-Jurciukonis
Mar 12, 2026

Can it be generated only on composer update instead of cache clearing.
We jump back-and-forth between mutlitple older or newer branches to fix features. This file is commited in or another state, but is always re-generated is get's in the way of changed files. You must be carful not to commit this not intended change.
Very annoying

2 replies

okorneliuk Mar 23, 2026

Totally agreed. When I use YAML config, I don't even need this file. Separate console command would be the most flexible idea.

uncaught Apr 13, 2026

Do you know if there is an open issue for this? This is happening to us quite frequently, too. I can imagine the bigger the team this gets quite annoying.

kevinpapst · 2026-04-30T15:59:58Z

kevinpapst
Apr 30, 2026

Just adding my vote for "this should be configurable and improved".
The initial blog post also raised a few concerns.
This file does not belong into the config/ directory and .gitignore is really not a long term solution.

1 reply

simPod Jun 30, 2026

I just removed it and gitignored it.

I is not a solution but the value added of the file compared to the burden it caused was not worth it.

okorneliuk · 2026-07-17T08:10:08Z

okorneliuk
Jul 17, 2026

Following approach seems to be working for me in multi-kernel configuration:

class Kernel extends BaseKernel
{
    use MicroKernelTrait { getConfigDir as getSharedConfigDir; }

    public function __construct(string $environment, bool $debug, public readonly string $id)
    {
        parent::__construct($environment, $debug);
    }
    
    public function getConfigDir(): string
    {
        return $this->getProjectDir().'/apps/'.$this->id.'/config';
    }

    // ...
}

It generates reference.php per application, but be careful ❗ - now your main config directory is config of the application, not the shared one. Shared config directory is availabel as getSharedConfigDir()

0 replies

Uh oh!

Uh oh!

reference.php #62588

Uh oh!

Replies: 5 comments · 8 replies

Uh oh!

Uh oh!

GromNaN Dec 1, 2025 Collaborator

Uh oh!

Uh oh!

Uh oh!

GromNaN Feb 6, 2026 Collaborator

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Replies: 5 comments 8 replies

GromNaN
Dec 1, 2025
Collaborator

GromNaN Feb 6, 2026
Collaborator