8000 document new framework.assets.json_manifest_path option · symfony/symfony-docs@08d2af6 · GitHub
[go: up one dir, main page]
Skip to content

Commit 08d2af6

Browse files
robfrawleyrobfrawley
committed
document new framework.assets.json_manifest_path option
1 parent b1f957f commit 08d2af6

File tree

6 files changed

+133
-18
lines changed

6 files changed

+133
-18
lines changed

‎assetic/asset_management.rst

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -552,10 +552,11 @@ done from the template and is relative to the public document root:
552552
553553
.. note::
554554

555-
Symfony also contains a method for cache *busting*, where the final URL
556-
generated by Assetic contains a query parameter that can be incremented
557-
via configuration on each deployment. For more information, see the
558-
:ref:`reference-framework-assets-version` configuration option.
555+
Symfony provides various cache busting implementations via the
556+
:ref:`version <reference-framework-assets-version>`,
557+
:ref:`version_format <reference-assets-version-format>`, and
558+
:ref:`json_manifest_path <reference-assets-json-manifest-path>`
559+
configuration options.
559560

560561
.. _assetic-dumping:
561562

‎frontend.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ working with CSS and JavaScript a joy. You can use it, use something else, or ju
66
create static CSS and JS files in your ``web/`` directory and include them in your
77
templates.
88

9+
.. _frontend-webpack-encore:
10+
911
Webpack Encore
1012
--------------
1113

‎frontend/custom_version_strategy.rst

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,17 @@ applications by adding a version identifier to the URL of the static assets
1010
identifier is also modified to force the browser to download it again instead of
1111
reusing the cached asset.
1212

13-
Symfony supports asset versioning thanks to the :ref:`version <reference-framework-assets-version>`
14-
and :ref:`version_format <reference-assets-version-format>` configuration
15-
options. If your application requires a more advanced versioning, such as
16-
generating the version dynamically based on some external information, you can
17-
create your own version strategy.
13+
If your application requires advanced versioning, such as generating the
14+
version dynamically based on some external information, you can create your
15+
own version strategy.
16+
17+
.. note::
18+
19+
Symfony provides various cache busting implementations via the
20+
:ref:`version <reference-framework-assets-version>`,
21+
:ref:`version_format <reference-assets-version-format>`, and
22+
:ref:`json_manifest_path <reference-assets-json-manifest-path>`
23+
configuration options.
1824

1925
Creating your Own Asset Version Strategy
2026
----------------------------------------

‎reference/configuration/framework.rst

Lines changed: 105 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ Configuration
7171
* `version_strategy`_
7272
* `version`_
7373
* `version_format`_
74+
* `json_manifest_path`_
7475
* `templating`_
7576
* `hinclude_default_template`_
7677
* :ref:`form <reference-templating-form>`
@@ -980,6 +981,7 @@ Each package can configure the following options:
980981
* :ref:`version_strategy <reference-assets-version-strategy>`
981982
* :ref:`version <reference-framework-assets-version>`
982983
* :ref:`version_format <reference-assets-version-format>`
984+
* :ref:`json_manifest_path <reference-assets-json-manifest-path>`
983985

984986
.. _reference-framework-assets-version:
985987
.. _ref-framework-assets-version:
@@ -1054,7 +1056,7 @@ option.
10541056

10551057
.. note::
10561058

1057-
This parameter cannot be set at the same time as ``version_strategy``.
1059+
This parameter cannot be set at the same time as ``version_strategy`` or ``json_manifest_path``.
10581060

10591061
.. tip::
10601062

@@ -1187,7 +1189,106 @@ individually for each asset package:
11871189
11881190
.. note::
11891191

1190-
This parameter cannot be set at the same time as ``version``.
1192+
This parameter cannot be set at the same time as ``version`` or ``json_manifest_path``.
1193+
1194+
.. _reference-assets-json-manifest-path:
1195+
.. _reference-templating-json-manifest-path:
1196+
1197+
json_manifest_path
1198+
..................
1199+
1200+
**type**: ``string`` **default**: ``null``
1201+
1202+
.. versionadded:: 3.3
1203+
1204+
The ``json_manifest_path`` option was introduced in Symfony 3.3.
1205+
1206+
The file path to a ``manifest.json`` file containing an associative array of asset
1207+
names and their respective compiled names. A common cache-busting technique using
1208+
a "manifest" file works by writing out assets with a "hash" appended to their
1209+
file names (e.g. ``main.ae433f1cb.css``) during a front-end compilation routine.
1210+
1211+
.. tip::
1212+
1213+
Symfony's
1214+
:ref:`Webpack Encore <frontend-webpack-encore>` supports
1215+
:ref:`outputting hashed assets <encore-long-term-caching>`. Moreover, this can
1216+
be incorporate this into many other workflows, including Webpack and Gulp using
1217+
`webpack-manifest-plugin`_ and `gulp-rev`_, respectfully.
1218+
1219+
This option can be set globally for all assets and individually for each asset
1220+
package:
1221+
1222+
.. configuration-block::
1223+
1224+
.. code-block:: yaml
1225+
1226+
# app/config/config.yml
1227+
framework:
1228+
assets:
1229+
# this manifest is applied to every asset (including packages)
1230+
json_manifest_path: "%kernel.project_dir%/web/assets/manifest.json"
1231+
packages:
1232+
foo_package:
1233+
# this package uses its own manifest (the default file is ignored)
1234+
json_manifest_path: "%kernel.project_dir%/web/assets/a_different_manifest.json"
1235+
bar_package:
1236+
# this package uses the global manifest (the default file is used)
1237+
base_path: '/images'
1238+
1239+
.. code-block:: xml
1240+
1241+
<!-- app/config/config.xml -->
1242+
<?xml version="1.0" encoding="UTF-8" ?>
1243+
<container xmlns="http://symfony.com/schema/dic/services"
1244+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1245+
xmlns:framework="http://symfony.com/schema/dic/symfony"
1246+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
1247+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
1248+
1249+
<framework:config>
1250+
<framework:assets json_manifest_path="%kernel.project_dir%/web/assets/manifest.json">
1251+
<!-- this package removes the manifest (the file will not apply) -->
1252+
<framework:package
1253+
name="foo_package"
1254+
json_manifest_path="%kernel.project_dir%/web/assets/a_different_manifest.json" />
1255+
<!-- this package uses the global manifest (the default file is used) -->
1256+
<framework:package
1257+
name="bar_package"
1258+
base_path="/images" />
1259+
</framework:assets>
1260+
</framework:config>
1261+
</container>
1262+
1263+
.. code-block:: php
1264+
1265+
// app/config/config.php
1266+
$container->loadFromExtension('framework', array(
1267+
'assets' => array(
1268+
'json_manifest_path' => '%kernel.project_dir%/web/assets/manifest.json',
1269+
'packages' => array(
1270+
'foo_package' => array(
1271+
// this package uses its own manifest (the default file is ignored)
1272+
'json_manifest_path' => '%kernel.project_dir%/web/assets/a_different_manifest.json',
1273+
),
1274+
'bar_package' => array(
1275+
// this package uses the global manifest (the default file is used)
1276+
'json_manifest_path' => '/images',
1277+
),
1278+
),
1279+
),
1280+
));
1281+
1282+
.. note::
1283+
1284+
This parameter cannot be set at the same time as ``version`` or ``version_strategy``.
1285+
Additionally, this option cannot be nullified at the package scope if a global manifest
1286+
file is specified.
1287+
1288+
.. tip::
1289+
1290+
If you request an asset that is *not found* in the ``manifest.json`` file, the original -
1291+
*unmodified* - asset path will be returned.
11911292

11921293
templating
11931294
~~~~~~~~~~
@@ -1901,3 +2002,5 @@ Full Default Configuration
19012002
.. _`PhpStormProtocol`: https://github.com/aik099/PhpStormProtocol
19022003
.. _`phpstorm-url-handler`: https://github.com/sanduhrs/phpstorm-url-handler
19032004
.. _`blue/green deployment`: http://martinfowler.com/bliki/BlueGreenDeployment.html
2005+
.. _`gulp-rev`: https://www.npmjs.com/package/gulp-rev
2006+
.. _`webpack-manifest-plugin`: https://www.npmjs.com/package/webpack-manifest-plugin

‎reference/twig_reference.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -123,8 +123,10 @@ asset
123123

124124
Returns a public path to ``path``, which takes into account the base path
125125
set for the package and the URL path. More information in
126-
:ref:`templating-assets`. For asset versioning, see
127-
:ref:`reference-framework-assets-version`.
126+
:ref:`templating-assets`. Symfony provides various cache busting
127+
implementations via the :ref:`reference-framework-assets-version`,
128+
:ref:`reference-assets-version-strategy`, and
129+
:ref:`reference-assets-json-manifest-path` configuration options.
128130

129131
asset_version
130132
~~~~~~~~~~~~~~

‎templating.rst

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -771,11 +771,12 @@ should render with the subdirectory (e.g. ``/my_app/images/logo.png``). The
771771
``asset()`` function takes care of this by determining how your application is
772772
being used and generating the correct paths accordingly.
773773

774-
Additionally, if you use the ``asset()`` function, Symfony can automatically
775-
append a query string to your asset, in order to guarantee that updated static
776-
assets won't be loaded from cache after being deployed. For example, ``/images/logo.png`` might
777-
look like ``/images/logo.png?v2``. For more information, see the :ref:`reference-framework-assets-version`
778-
configuration option.
774+
.. tip::
775+
776+
The ``asset()`` function supports various cache busting techniques via the
777+
:ref:`version <reference-framework-assets-version>`,
778+
:ref:`version_format <reference-assets-version-format>`, and
779+
:ref:`json_manifest_path <reference-assets-json-manifest-path>` configuration options.
779780

780781
If you need absolute URLs for assets, use the ``absolute_url()`` Twig function
781782
as follows:

0 commit comments

Comments
 (0)
0