minor #14414 [Asset] Add option $strictMode to JsonManifestVersionStrategy (GromNaN)

This PR was merged into the 5.4 branch.

Discussion
----------

[Asset] Add option $strictMode to JsonManifestVersionStrategy

Documentation for symfony/symfony#38495

Commits
-------

c4e19eb [Assets] Add doc for strict mode strategy

Author: javiereguiluz

components/asset.rst

@@ -167,6 +167,26 @@ In those cases, use the
     echo $package->getUrl('css/app.css');
     // result: build/css/app.b916426ea1d10021f3f17ce8031f93c2.css
 
+If you request an asset that is *not found* in the ``rev-manifest.json`` file, the original -
+*unmodified* - asset path will be returned.
+The ``$strictMode`` argument helps for debugging as it throws an exception when the asset is
+not listed in the manifest::
+
+    use Symfony\Component\Asset\Package;
+    use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy;
+
+    // The value of $strictMode can be specific per environment "true" for debugging and "false" for stability.
+    $strictMode = true;
+    // assumes the JSON file above is called "rev-manifest.json"
+    $package = new Package(new JsonManifestVersionStrategy(__DIR__.'/rev-manifest.json', null, $strictMode));
+
+    echo $package->getUrl('not-found.css');
+    // error:
+
+.. versionadded:: 5.4
+
+    The ``$strictMode`` option was introduced in Symfony 5.4.
+
 If your JSON file is not on your local filesystem but is accessible over HTTP,
 use the :class:`Symfony\\Component\\Asset\\VersionStrategy\\RemoteJsonManifestVersionStrategy`
 with the :doc:`HttpClient component </http_client>`::

reference/configuration/framework.rst

@@ -1879,6 +1879,7 @@ Each package can configure the following options:
 * :ref:`version <reference-framework-assets-version>`
 * :ref:`version_format <reference-assets-version-format>`
 * :ref:`json_manifest_path <reference-assets-json-manifest-path>`
+* :ref:`strict_mode <reference-assets-strict-mode>`
 
 .. _reference-framework-assets-version:
 .. _ref-framework-assets-version:
@@ -2122,6 +2123,8 @@ package:
                     foo_package:
                         # this package uses its own manifest (the default file is ignored)
                         json_manifest_path: "%kernel.project_dir%/public/build/a_different_manifest.json"
+                        # Throws an exception when an asset is not found in the manifest
+                        strict_mode: %kernel.debug%
                     bar_package:
                         # this package uses the global manifest (the default file is used)
                         base_path: '/images'
@@ -2142,9 +2145,10 @@ package:
                 <!-- you can use absolute URLs too and Symfony will download them automatically -->
                 <!-- <framework:assets json-manifest-path="https://cdn.example.com/manifest.json"> -->
                     <!-- this package uses its own manifest (the default file is ignored) -->
+                    <!-- Throws an exception when an asset is not found in the manifest -->
                     <framework:package
                         name="foo_package"
-                        json-manifest-path="%kernel.project_dir%/public/build/a_different_manifest.json"/>
+                        json-manifest-path="%kernel.project_dir%/public/build/a_different_manifest.json" strict-mode="%kernel.debug%"/>
                     <!-- this package uses the global manifest (the default file is used) -->
                     <framework:package
                         name="bar_package"
@@ -2168,7 +2172,9 @@ package:
             // 'json_manifest_path' => 'https://cdn.example.com/manifest.json',
             $framework->assets()->package('foo_package')
                 // this package uses its own manifest (the default file is ignored)
-                ->jsonManifestPath('%kernel.project_dir%/public/build/a_different_manifest.json');
+                ->jsonManifestPath('%kernel.project_dir%/public/build/a_different_manifest.json')
+                // Throws an exception when an asset is not found in the manifest
+                ->setStrictMode('%kernel.debug%');
 
             $framework->assets()->package('bar_package')
                 // this package uses the global manifest (the default file is used)
@@ -2190,11 +2196,26 @@ package:
 
     If you request an asset that is *not found* in the ``manifest.json`` file, the original -
     *unmodified* - asset path will be returned.
+    Since Symfony 5.4, you can set ``strict_mode`` to ``true`` to get an exception when an asset is *not found*.
 
 .. note::
 
     If an URL is set, the JSON manifest is downloaded on each request using the `http_client`_.
 
+.. _reference-assets-strict-mode:
+
+strict_mode
+...........
+
+**type**: ``boolean`` **default**: ``false``
+
+When enabled, the strict mode assert that all requested assets are in the manifest file.
+This option is useful to detect typo or missing assets, the recommended value is ``%kernel.debug%``.
+
+.. versionadded:: 5.4
+
+    This option was introduced in Symfony 5.4.
+
 translator
 ~~~~~~~~~~