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

Commit 74df78e

Browse files
robfrawleyrobfrawley
committed
document new framework.assets.json_manifest_path option
1 parent a95f4f0 commit 74df78e

File tree

2 files changed

+96
-3
lines changed

2 files changed

+96
-3
lines changed

‎frontend/custom_version_strategy.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,10 @@ 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
13+
Symfony supports asset versioning thanks to the
14+
:ref:`version <reference-framework-assets-version>`,
15+
:ref:`version_format <reference-assets-version-format>`, and
16+
:ref:`json_manifest_path <reference-assets-json-manifest-path>` configuration
1517
options. If your application requires a more advanced versioning, such as
1618
generating the version dynamically based on some external information, you can
1719
create your own version strategy.

‎reference/configuration/framework.rst

Lines changed: 92 additions & 1 deletion
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:
@@ -1187,7 +1189,94 @@ 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+
1196+
json_manifest_path
1197+
..................
1198+
1199+
**type**: ``string`` **default**: ``null``
1200+
1201+
.. versionadded:: 3.3
1202+
1203+
The ``json_manifest_path`` option was introduced in Symfony 3.3.
1204+
1205+
The file path to a ``manifest.json`` file containing an associative array of asset
1206+
names and their respective compiled names. A common cache-busting technique using
1207+
a ``manifest.json`` file works by writing out assets with a "hash" appended to their
1208+
file names (e.g. ``main.ae433f1cb.css``). You can incorporate this into many work
1209+
flows, including Webpack and Gulp using `webpack-manifest-plugin`_ and `gulp-rev`_,
1210+
respectfully.
1211+
1212+
This option can be set globally for all assets and individually for each asset
1213+
package:
1214+
1215+
.. configuration-block::
1216+
1217+
.. code-block:: yaml
1218+
1219+
# app/config/config.yml
1220+
framework:
1221+
assets:
1222+
# this manifest is applied to every asset (including packages)
1223+
json_manifest_path: "%kernel.project_dir%/web/assets/manifest.json"
1224+
packages:
1225+
foo_package:
1226+
# this package uses its own manifest (the default file is ignored)
1227+
json_manifest_path: "%kernel.project_dir%/web/assets/a_different_manifest.json"
1228+
bar_package:
1229+
# this package uses the global manifest (the default file is used)
1230+
base_path: '/images'
1231+
1232+
.. code-block:: xml
1233+
1234+
<!-- app/config/config.xml -->
1235+
<?xml version="1.0" encoding="UTF-8" ?>
1236+
<container xmlns="http://symfony.com/schema/dic/services"
1237+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1238+
xmlns:framework="http://symfony.com/schema/dic/symfony"
1239+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
1240+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
1241+
1242+
<framework:config>
1243+
<framework:assets json_manifest_path="%kernel.project_dir%/web/assets/manifest.json">
1244+
<!-- this package removes the manifest (the file will not apply) -->
1245+
<framework:package
1246+
name="foo_package"
1247+
json_manifest_path="%kernel.project_dir%/web/assets/a_different_manifest.json" />
1248+
<!-- this package uses the global manifest (the default file is used) -->
1249+
<framework:package
1250+
name="bar_package"
1251+
base_path="/images" />
1252+
</framework:assets>
1253+
</framework:config>
1254+
</container>
1255+
1256+
.. code-block:: php
1257+
1258+
// app/config/config.php
1259+
$container->loadFromExtension('framework', array(
1260+
'assets' => array(
1261+
'json_manifest_path' => '%kernel.project_dir%/web/assets/manifest.json',
1262+
'packages' => array(
1263+
'foo_package' => array(
1264+
// this package uses its own manifest (the default file is ignored)
1265+
'json_manifest_path' => '%kernel.project_dir%/web/assets/a_different_manifest.json',
1266+
),
1267+
'bar_package' => array(
1268+
// this package uses the global manifest (the default file is used)
1269+
'json_manifest_path' => '/images',
1270+
),
1271+
),
1272 9091 +
),
1273+
));
1274+
1275+
.. note::
1276+
1277+
This parameter cannot be set at the same time as ``version`` or ``version_strategy``.
1278+
Additionally, this option cannot be nullified at the package scope if a global manifest
1279+
file is specified.
11911280

11921281
templating
11931282
~~~~~~~~~~
@@ -1901,3 +1990,5 @@ Full Default Configuration
19011990
.. _`PhpStormProtocol`: https://github.com/aik099/PhpStormProtocol
19021991
.. _`phpstorm-url-handler`: https://github.com/sanduhrs/phpstorm-url-handler
19031992
.. _`blue/green deployment`: http://martinfowler.com/bliki/BlueGreenDeployment.html
1993+
.. _`gulp-rev`: https://www.npmjs.com/package/gulp-rev
1994+
.. _`webpack-manifest-plugin`: https://www.npmjs.com/package/webpack-manifest-plugin

0 commit comments

Comments
 (0)
0