feature #22 [Cache] Cache the parsed entrypoints.json (Kocal)

This PR was squashed before being merged into the main branch.

Discussion
----------

[Cache] Cache the parsed entrypoints.json

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | -
| License       | MIT

Adds an opt-in `cache` config key to `RepriseBundle` (default `false`), mirroring the option WebpackEncoreBundle already has.

Right now, under PHP-FPM, `EntrypointsLookup` re-reads and `json_decode`s `entrypoints.json` on every single request before it can resolve one URL. With `cache: true`, the file is parsed once during `cache:warmup` and the resulting `Entrypoints` object is compiled into a `PhpArrayAdapter` file (`%kernel.build_dir%/reprise.cache.php`). At runtime the bundle just reads that object back instead of decoding JSON on each request.

A few implementation details worth flagging for review:

- `EntrypointsLookup` now goes through an optional PSR-6 cache: hit returns the cached object, miss reads the file and saves it. With `cache: false` (the default), nothing changes.
- `EntrypointsCacheWarmer` writes the compiled file and never throws: a missing or malformed `entrypoints.json` at deploy time shouldn't be able to break `cache:warmup`.
- What gets cached is the built `Entrypoints` object, not the raw array. `PhpArrayAdapter` exports it via `symfony/var-exporter`, which handles the bundle's `final`/`readonly` classes without needing `__set_state`. Nice side effect: validation runs once at warmup instead of on every request.
- The cache pool and warmer are only wired when `cache: true`, behind a `class_exists()` guard that gives a clear error if the Cache component isn't there. `symfony/cache` and `symfony/var-exporter` stay `require-dev`, so projects that don't enable caching don't pull them in.
- The cache is keyed once (Reprise is mono-build), and it's refreshed by your deploy's `cache:clear` + `cache:warmup`. So after rebuilding assets, run `cache:clear`. This is a production optimization, not something you'd want in dev.

## Usage

```yaml
# config/packages/reprise.yaml
reprise:
    cache: true
```

Enabling it requires the Cache component:

```
$ composer require symfony/cache
```

## Testing

Unit tests cover the cache read path (`ArrayAdapter`) and the warmer (round-tripping a real compiled file), plus a functional test booting a `cache: true` kernel. Added a `cache` entry to the Configuration section of `doc/index.rst`.

Commits
-------

f34968e [Cache] Cache the parsed entrypoints.json

Author: Kocal

.gitignore

@@ -23,3 +23,6 @@ node_modules/
 
 # PHP-CS-Fixer
 /.php-cs-fixer.cache
+
+# Symfony config-builder reference, regenerated by the test kernel's cache warmer.
+/config/reference.php

.php-cs-fixer.dist.php

@@ -59,7 +59,7 @@ public function getRuleCustomisers(): array
                     $relativePathname = $file->getRelativePathname();
 
                     if (
-                        str_contains($relativePathname, '/tests/') // don't touch test files, as massive change with little benefit - as outside of public contract anyway
+                        str_contains($relativePathname, 'tests/') // don't touch test files, as massive change with little benefit - as outside of public contract anyway
                         || str_contains($relativePathname, '/Test/') // public namespace not following the rule, do not mistake it with `/Tests/`
                     ) {
                         return false;

composer.json

@@ -24,7 +24,9 @@
         "phpunit/phpunit": "^13.2",
         "phpstan/phpstan": "^2.2",
         "friendsofphp/php-cs-fixer": "^3.95",
-        "symfony/web-link": "^7.4|^8.0"
+        "symfony/web-link": "^7.4|^8.0",
+        "symfony/cache": "^7.4|^8.0",
+        "symfony/var-exporter": "^7.4|^8.0"
     },
     "autoload": {
         "psr-4": { "Symfony\\Reprise\\": "src/" }

config/cache.php

@@ -0,0 +1,40 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+use Symfony\Component\Cache\Adapter\PhpArrayAdapter;
+use Symfony\Reprise\CacheWarmer\EntrypointsCacheWarmer;
+
+return static function (ContainerConfigurator $container): void {
+    $services = $container->services();
+
+    $services->set('cache.reprise')
+        ->parent('cache.system')
+        ->tag('cache.pool')
+    ;
+
+    $services->set('reprise.cache', PhpArrayAdapter::class)
+        ->args([
+            '%kernel.build_dir%/reprise.cache.php',
+            service('cache.reprise'),
+        ])
+    ;
+
+    $services->set('reprise.entrypoints_cache_warmer', EntrypointsCacheWarmer::class)
+        ->args([
+            param('reprise.entrypoints_path'),
+            'reprise.entrypoints',
+            service('reprise.cache'),
+        ])
+        ->tag('kernel.cache_warmer')
+    ;
+};

doc/index.rst

@@ -154,6 +154,9 @@ Reprise exposes a few optional settings under its own configuration, all shown h
         # Throw when entrypoints.json or a requested entry is missing, instead of rendering nothing.
         strict_mode: true
 
+        # Cache the parsed entrypoints.json in a compiled PHP file, warmed at cache:warmup (needs symfony/cache).
+        cache: false
+
         # A framework.assets package name used to resolve entry URLs. null uses the default package.
         asset_package: null
 
@@ -171,6 +174,9 @@ Reprise exposes a few optional settings under its own configuration, all shown h
   own ``outputPath``.
 - ``strict_mode``: when ``true`` (the default), throws a clear exception on a missing file or an unknown entry; when
   ``false``, renders nothing instead.
+- ``cache``: when ``true``, parse ``entrypoints.json`` once at ``cache:warmup`` and read it from a compiled PHP file
+  at runtime instead of decoding the JSON on every request. Enable it in production and run ``cache:clear`` after
+  rebuilding your assets; it needs ``symfony/cache`` (``composer require symfony/cache``).
 - ``asset_package``: resolve entry URLs through a specific ``framework.assets`` package instead of the default one.
   You only need this if your default package applies a version strategy, which would re-hash files Reprise already
   content-hashed and break the URLs. Point it at a package with ``version: false`` (see below).