From f7c7b569f001cde2d5b41b65e30d38aacec75e0d Mon Sep 17 00:00:00 2001 From: Rob Frawley 2nd Date: Tue, 6 Jun 2017 21:24:40 -0400 Subject: [PATCH] document new framework.assets.json_manifest_path option --- assetic/asset_management.rst | 9 ++- frontend.rst | 2 + frontend/custom_version_strategy.rst | 16 ++-- reference/configuration/framework.rst | 106 +++++++++++++++++++++++++- reference/twig_reference.rst | 6 +- templating.rst | 11 +-- 6 files changed, 132 insertions(+), 18 deletions(-) diff --git a/assetic/asset_management.rst b/assetic/asset_management.rst index 4a78a7741b9..d69315f65c1 100644 --- a/assetic/asset_management.rst +++ b/assetic/asset_management.rst @@ -552,10 +552,11 @@ done from the template and is relative to the public document root: .. note:: - Symfony also contains a method for cache *busting*, where the final URL - generated by Assetic contains a query parameter that can be incremented - via configuration on each deployment. For more information, see the - :ref:`reference-framework-assets-version` configuration option. + Symfony provides various cache busting implementations via the + :ref:`version `, + :ref:`version_format `, and + :ref:`json_manifest_path ` + configuration options. .. _assetic-dumping: diff --git a/frontend.rst b/frontend.rst index 7dab845044d..4db7b1d0f4d 100644 --- a/frontend.rst +++ b/frontend.rst @@ -6,6 +6,8 @@ working with CSS and JavaScript a joy. You can use it, use something else, or ju create static CSS and JS files in your ``web/`` directory and include them in your templates. +.. _frontend-webpack-encore: + Webpack Encore -------------- diff --git a/frontend/custom_version_strategy.rst b/frontend/custom_version_strategy.rst index 940e258b3e8..1dcd2754667 100644 --- a/frontend/custom_version_strategy.rst +++ b/frontend/custom_version_strategy.rst @@ -10,11 +10,17 @@ applications by adding a version identifier to the URL of the static assets identifier is also modified to force the browser to download it again instead of reusing the cached asset. -Symfony supports asset versioning thanks to the :ref:`version ` -and :ref:`version_format ` configuration -options. If your application requires a more advanced versioning, such as -generating the version dynamically based on some external information, you can -create your own version strategy. +If your application requires advanced versioning, such as generating the +version dynamically based on some external information, you can create your +own version strategy. + +.. note:: + + Symfony provides various cache busting implementations via the + :ref:`version `, + :ref:`version_format `, and + :ref:`json_manifest_path ` + configuration options. Creating your Own Asset Version Strategy ---------------------------------------- diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 8249ec12eec..85c149348f0 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -71,6 +71,7 @@ Configuration * `version_strategy`_ * `version`_ * `version_format`_ + * `json_manifest_path`_ * `templating`_ * `hinclude_default_template`_ * :ref:`form ` @@ -980,6 +981,7 @@ Each package can configure the following options: * :ref:`version_strategy ` * :ref:`version ` * :ref:`version_format ` +* :ref:`json_manifest_path ` .. _reference-framework-assets-version: .. _ref-framework-assets-version: @@ -1054,7 +1056,7 @@ option. .. note:: - This parameter cannot be set at the same time as ``version_strategy``. + This parameter cannot be set at the same time as ``version_strategy`` or ``json_manifest_path``. .. tip:: @@ -1187,7 +1189,105 @@ individually for each asset package: .. note:: - This parameter cannot be set at the same time as ``version``. + This parameter cannot be set at the same time as ``version`` or ``json_manifest_path``. + +.. _reference-assets-json-manifest-path: +.. _reference-templating-json-manifest-path: + +json_manifest_path +.................. + +**type**: ``string`` **default**: ``null`` + +.. versionadded:: 3.3 + + The ``json_manifest_path`` option was introduced in Symfony 3.3. + +The file path to a ``manifest.json`` file containing an associative array of asset +names and their respective compiled names. A common cache-busting technique using +a "manifest" file works by writing out assets with a "hash" appended to their +file names (e.g. ``main.ae433f1cb.css``) during a front-end compilation routine. + +.. tip:: + + Symfony's :ref:`Webpack Encore ` supports + :ref:`outputting hashed assets `. Moreover, this + can be incorporate this into many other workflows, including Webpack and + Gulp using `webpack-manifest-plugin`_ and `gulp-rev`_, respectfully. + +This option can be set globally for all assets and individually for each asset +package: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + assets: + # this manifest is applied to every asset (including packages) + json_manifest_path: "%kernel.project_dir%/web/assets/manifest.json" + packages: + foo_package: + # this package uses its own manifest (the default file is ignored) + json_manifest_path: "%kernel.project_dir%/web/assets/a_different_manifest.json" + bar_package: + # this package uses the global manifest (the default file is used) + base_path: '/images' + + .. code-block:: xml + + + + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + 'assets' => array( + 'json_manifest_path' => '%kernel.project_dir%/web/assets/manifest.json', + 'packages' => array( + 'foo_package' => array( + // this package uses its own manifest (the default file is ignored) + 'json_manifest_path' => '%kernel.project_dir%/web/assets/a_different_manifest.json', + ), + 'bar_package' => array( + // this package uses the global manifest (the default file is used) + 'json_manifest_path' => '/images', + ), + ), + ), + )); + +.. note:: + + This parameter cannot be set at the same time as ``version`` or ``version_strategy``. + Additionally, this option cannot be nullified at the package scope if a global manifest + file is specified. + +.. tip:: + + If you request an asset that is *not found* in the ``manifest.json`` file, the original - + *unmodified* - asset path will be returned. templating ~~~~~~~~~~ @@ -1901,3 +2001,5 @@ Full Default Configuration .. _`PhpStormProtocol`: https://github.com/aik099/PhpStormProtocol .. _`phpstorm-url-handler`: https://github.com/sanduhrs/phpstorm-url-handler .. _`blue/green deployment`: http://martinfowler.com/bliki/BlueGreenDeployment.html +.. _`gulp-rev`: https://www.npmjs.com/package/gulp-rev +.. _`webpack-manifest-plugin`: https://www.npmjs.com/package/webpack-manifest-plugin \ No newline at end of file diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst index 24fbf4f9ce5..f4f2229052c 100644 --- a/reference/twig_reference.rst +++ b/reference/twig_reference.rst @@ -123,8 +123,10 @@ asset Returns a public path to ``path``, which takes into account the base path set for the package and the URL path. More information in -:ref:`templating-assets`. For asset versioning, see -:ref:`reference-framework-assets-version`. +:ref:`templating-assets`. Symfony provides various cache busting +implementations via the :ref:`reference-framework-assets-version`, +:ref:`reference-assets-version-strategy`, and +:ref:`reference-assets-json-manifest-path` configuration options. asset_version ~~~~~~~~~~~~~~ diff --git a/templating.rst b/templating.rst index e87e8885cdd..6970aa852fd 100644 --- a/templating.rst +++ b/templating.rst @@ -771,11 +771,12 @@ should render with the subdirectory (e.g. ``/my_app/images/logo.png``). The ``asset()`` function takes care of this by determining how your application is being used and generating the correct paths accordingly. -Additionally, if you use the ``asset()`` function, Symfony can automatically -append a query string to your asset, in order to guarantee that updated static -assets won't be loaded from cache after being deployed. For example, ``/images/logo.png`` might -look like ``/images/logo.png?v2``. For more information, see the :ref:`reference-framework-assets-version` -configuration option. +.. tip:: + + The ``asset()`` function supports various cache busting techniques via the + :ref:`version `, + :ref:`version_format `, and + :ref:`json_manifest_path ` configuration options. If you need absolute URLs for assets, use the ``absolute_url()`` Twig function as follows: