8000 [reference] Adding details about assets_version and assets_version_fo… · mdpatrick/symfony-docs@3162e83 · GitHub
[go: up one dir, main page]
Skip to content

Commit 3162e83

Browse files
weaverryanweaverryan
committed
[reference] Adding details about assets_version and assets_version_format - closes symfony#688 
1 parent 8f6d487 commit 3162e83

File tree

3 files changed

+91
-1
lines changed

3 files changed

+91
-1
lines changed

‎book/templating.rst

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

782+
Additionally, if you use the ``asset`` function, Symfony can automatically
783+
append a query string to your asset, in order to guarantee that updated static
784+
assets won't be cached when deployed. For example, ``/images/logo.png`` might
785+
look like ``/images/logo.png?v2``. For more information, see the :ref:`ref-framework-assets-version`
786+
configuration option.
787+
782788
.. index::
783789
single: Templating; Including stylesheets and Javascripts
784790
single: Stylesheets; Including stylesheets

‎cookbook/assetic/asset_management.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,14 @@ done from the template and is relative to the public document root:
211211
<script src="<?php echo $view->escape($url) ?>"></script>
212212
<?php endforeach; ?>
213213
214+
.. note::
215+
216+
Symfony also contains a method for cache *busting*, where the final URL
217+
generated by assetic in the ``prod`` environment contains a query parameter
218+
that can be incremented via configuration on each deployment. For more
219+
information, see the :ref:`ref-framework-assets-version` configuration
220+
option.
221+
214222
Caching the output
215223
------------------
216224

‎reference/configuration/framework.rst

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ Configuration
2626
* `field_name`
2727
* `session`_
2828
* `lifetime`_
29+
* `templating`_
30+
* `assets_version`_
31+
* `assets_version_format`_
2932

3033
charset
3134
~~~~~~~
@@ -100,6 +103,79 @@ lifetime
100103

101104
This determines the lifetime of the session - in seconds.
102105

106+
templating
107+
108+
.. _ref-framework-assets-version:
109+
110+
assets_version
111+
..............
112+
113+
**type**: ``string``
114+
115+
This option is used to *bust* the cache on assets by globally adding a query
116+
parameter to all rendered asset paths (e.g. ``/images/logo.png?v2``). This
117+
applies only to assets rendered via the Twig ``asset`` function (or PHP equivalent)
118+
as well as assets rendered with assetic.
119+
120+
For example, suppose you have the following:
121+
122+
.. configuration-block::
123+
124+
.. code-block:: html+jinja
125+
126+
<img src="{{ asset('images/logo.png') }}" alt="Symfony!" />
127+
128+
.. code-block:: php
129+
130+
<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>" alt="Symfony!" />
131+
132+
By default, this will render a path to your image such as ``/images/logo.png``.
133+
Now, activate the ``assets_version`` option:
134+
135+
.. configuration-block::
136+
137+
.. code-block:: yaml
138+
139+
# app/config/config.yml
140+
framework:
141+
# ...
142+
templating: { engines: ['twig'], assets_version: v2 }
143+
144+
.. code-block:: xml
145+
146+
<!-- app/config/config.xml -->
147+
<framework:templating assets-version="v2">
148+
<framework:engine id="twig" />
149+
</framework:templating>
150+
151+
.. code-block:: php
152+
153+
// app/config/config.php
154+
$container->loadFromExtension('framework', array(
155+
// ...
156+
'templating' => array(
157+
'engines' => array('twig'),
158+
'assets_version' => 'v2',
159+
),
160+
));
161+
162+
Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use
163+
this feature, you **must** manually increment the ``assets_version`` value
164+
before each deployment so that the query parameters change.
165+
166+
You can also control how the query string works via the `assets_version_format`_
167+
option.
168+
169+
assets_version_format
170+
.....................
171+
172+
**type**: ``string`` **default**: ``%s?%s``
173+
174+
This option relates to the `assets_version`_ option and controls exactly
175+
how the query string is constructed. For example, if ``assets_version_format``
176+
is set to ``%s?version=%s`` and ``assets_version`` is set to ``5``, rendered
177+
assets would look like ``/images/logo.png?version=5``.
178+
103179
Full Default Configuration
104180
--------------------------
105181

@@ -161,7 +237,7 @@ Full Default Configuration
161237
# templating configuration
162238
templating:
163239
assets_version: ~
164-
assets_version_format: ~ 4DBC
240+
assets_version_format: "%s?%s"
165241
assets_base_urls:
166242
http: []
167243
ssl: []

0 commit comments

Comments
 (0)
0