diff --git a/components/asset.rst b/components/asset.rst index 5044ef2dab9..cacb8bbe6c8 100644 --- a/components/asset.rst +++ b/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 `:: diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 6f09d0cb7b6..20687485b16 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -1879,6 +1879,7 @@ Each package can configure the following options: * :ref:`version ` * :ref:`version_format ` * :ref:`json_manifest_path ` +* :ref:`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: + + json-manifest-path="%kernel.project_dir%/public/build/a_different_manifest.json" strict-mode="%kernel.debug%"/> '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 ~~~~~~~~~~