8000 feature #8004 [WIP] Document "framework.assets.json_manifest_path" op… · symfony/symfony-docs@0d05b77 · GitHub
[go: up one dir, main page]
Skip to content

Commit 0d05b77

Browse files
xabbuhxabbuh
committed
feature #8004 [WIP] Document "framework.assets.json_manifest_path" option (robfrawley)
This PR was submitted for the master branch but it was merged into the 3.3 branch instead (closes #8004). Discussion ---------- [WIP] Document "framework.assets.json_manifest_path" option This pull request adds initial documentation for the newly introduced asset JSON manifest file path option: `framework.assets.json_manifest_path`. Resolves #7659. For reference on this new configuration option, see symfony/symfony#22046 and [symfony.com/blog/new-in-symfony-3-3-manifest-based-asset-versioning](https://symfony.com/blog/new-in-symfony-3-3-manifest-based-asset-versioning). Commits ------- 13a3070 document new framework.assets.json_manifest_path option
2 parents 0070ea8 + 13a3070 commit 0d05b77

File tree

6 files changed

+132
-18
lines changed

6 files changed

+132
-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: 104 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:
9E81 @@ -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,105 @@ 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 :ref:`Webpack Encore <frontend-webpack-encore>` supports
1214+
:ref:`outputting hashed assets <encore-long-term-caching>`. Moreover, this
1215+
can be incorporate this into many other workflows, including Webpack and
1216+
Gulp using `webpack-manifest-plugin`_ and `gulp-rev`_, respectfully.
1217+
1218+
This option can be set globally for all assets and individually for each asset
1219+
package:
1220+
1221+
.. configuration-block::
1222+
1223+
.. code-block:: yaml
1224+
1225+
# app/config/config.yml
1226+
framework:
1227+
assets:
1228+
# this manifest is applied to every asset (including packages)
1229+
json_manifest_path: "%kernel.project_dir%/web/assets/manifest.json"
1230+
packages:
1231+
foo_package:
1232+
# this package uses its own manifest (the default file is ignored)
1233+
json_manifest_path: "%kernel.project_dir%/web/assets/a_different_manifest.json"
1234+
bar_package:
1235+
# this package uses the global manifest (the default file is used)
1236+
base_path: '/images'
1237+
1238+
.. code-block:: xml
1239+
1240+
<!-- app/config/config.xml -->
1241+
<?xml version="1.0" encoding="UTF-8" ?>
1242+
<container xmlns="http://symfony.com/schema/dic/services"
1243+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1244+
xmlns:framework="http://symfony.com/schema/dic/symfony"
1245+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
1246+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
1247+
1248+
<framework:config>
1249+
<framework:assets json_manifest_path="%kernel.project_dir%/web/assets/manifest.json">
1250+
<!-- this package removes the manifest (the file will not apply) -->
1251+
<framework:package
1252+
name="foo_package"
1253+
json_manifest_path="%kernel.project_dir%/web/assets/a_different_manifest.json" />
1254+
<!-- this package uses the global manifest (the default file is used) -->
1255+
<framework:package
1256+
name="bar_package"
1257+
base_path="/images" />
1258+
</framework:assets>
1259+
</framework:config>
1260+
</container>
1261+
1262+
.. code-block:: php
1263+
1264+
// app/config/config.php
1265+
$container->loadFromExtension('framework', array(
1266+
'assets' => array(
1267+
'json_manifest_path' => '%kernel.project_dir%/web/assets/manifest.json',
1268+
'packages' => array(
1269+
'foo_package' => array(
1270+
// this package uses its own manifest (the default file is ignored)
1271+
'json_manifest_path' => '%kernel.project_dir%/web/assets/a_different_manifest.json',
1272+
),
1273+
'bar_package' => array(
1274+
// this package uses the global manifest (the default file is used)
1275+
'json_manifest_path' => '/images',
1276+
),
1277+
),
1278+
),
1279+
));
1280+
1281+
.. note::
1282+
1283+
This parameter cannot be set at the same time as ``version`` or ``version_strategy``.
1284+
Additionally, this option cannot be nullified at the package scope if a global manifest
1285+
file is specified.
1286+
1287+
.. tip::
1288+
1289+
If you request an asset that is *not found* in the ``manifest.json`` file, the original -
1290+
*unmodified* - asset path will be returned.
11911291

11921292
templating
11931293
~~~~~~~~~~
@@ -1901,3 +2001,5 @@ Full Default Configuration
19012001
.. _`PhpStormProtocol`: https://github.com/aik099/PhpStormProtocol
19022002
.. _`phpstorm-url-handler`: https://github.com/sanduhrs/phpstorm-url-handler
19032003
.. _`blue/green deployment`: http://martinfowler.com/bliki/BlueGreenDeployment.html
2004+
.. _`gulp-rev`: https://www.npmjs.com/package/gulp-rev
2005+
.. _`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