Skip to content

Commit

Permalink
change order of assets configuration options
Browse files Browse the repository at this point in the history
  • Loading branch information
Henry Snoek committed Feb 20, 2016
1 parent 61403e7 commit cc12d7f
Showing 1 changed file with 120 additions and 120 deletions.
240 changes: 120 additions & 120 deletions reference/configuration/framework.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,10 +70,10 @@ Configuration
* `gc_maxlifetime`_
* `save_path`_
* `assets`_
* `version`_
* `version_format`_
* `base_urls`_
* `packages`_
* `version`_
* `version_format`_
* `templating`_
* `hinclude_default_template`_
* :ref:`form <reference-templating-form>`
Expand Down Expand Up @@ -852,124 +852,6 @@ setting the value to ``null``:
assets
~~~~~~

.. _reference-framework-assets-version:
.. _ref-framework-assets-version:

version
.......

**type**: ``string``

This option is used to *bust* the cache on assets by globally adding a query
parameter to all rendered asset paths (e.g. ``/images/logo.png?v2``). This
applies only to assets rendered via the Twig ``asset`` function (or PHP
equivalent) as well as assets rendered with Assetic.

For example, suppose you have the following:

.. configuration-block::

.. code-block:: html+twig

<img src="{{ asset('images/logo.png') }}" alt="Symfony!" />

.. code-block:: php
<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>" alt="Symfony!" />
By default, this will render a path to your image such as ``/images/logo.png``.
Now, activate the ``version`` option:

.. configuration-block::

.. code-block:: yaml
# app/config/config.yml
framework:
# ...
assets:
version: 'v2'
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:assets version="v2">
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
// ...
'assets' => array(
'version' => 'v2',
),
));
Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use
this feature, you **must** manually increment the ``version`` value
before each deployment so that the query parameters change.

It's also possible to set the version value on an asset-by-asset basis (instead
of using the global version - e.g. ``v2`` - set here). See
:ref:`Versioning by Asset <book-templating-version-by-asset>` for details.

You can also control how the query string works via the `version_format`_
option.

.. tip::

As with all settings, you can use a parameter as value for the
``version``. This makes it easier to increment the cache on each
deployment.

.. _reference-templating-version-format:
.. _reference-assets-version-format:

version_format
..............

**type**: ``string`` **default**: ``%%s?%%s``

This specifies a :phpfunction:`sprintf` pattern that will be used with the
`version`_ option to construct an asset's path. By default, the pattern
adds the asset's version as a query string. For example, if
``version_format`` is set to ``%%s?version=%%s`` and ``version``
is set to ``5``, the asset's path would be ``/images/logo.png?version=5``.

.. note::

All percentage signs (``%``) in the format string must be doubled to
escape the character. Without escaping, values might inadvertently be
interpreted as :ref:`book-service-container-parameters`.

.. tip::

Some CDN's do not support cache-busting via query strings, so injecting
the version into the actual file path is necessary. Thankfully,
``version_format`` is not limited to producing versioned query
strings.

The pattern receives the asset's original path and version as its first
and second parameters, respectively. Since the asset's path is one
parameter, you cannot modify it in-place (e.g. ``/images/logo-v5.png``);
however, you can prefix the asset's path using a pattern of
``version-%%2$s/%%1$s``, which would result in the path
``version-5/images/logo.png``.

URL rewrite rules could then be used to disregard the version prefix
before serving the asset. Alternatively, you could copy assets to the
appropriate version path as part of your deployment process and forgot
any URL rewriting. The latter option is useful if you would like older
asset versions to remain accessible at their original URL.

.. _reference-templating-base-urls:
.. _reference-assets-base-urls:

Expand Down Expand Up @@ -1089,6 +971,124 @@ Each package can configure the following options:
* :ref:`version <reference-framework-assets-version>`
* :ref:`version_format <reference-assets-version-format>`

.. _reference-framework-assets-version:
.. _ref-framework-assets-version:

version
.......

**type**: ``string``

This option is used to *bust* the cache on assets by globally adding a query
parameter to all rendered asset paths (e.g. ``/images/logo.png?v2``). This
applies only to assets rendered via the Twig ``asset`` function (or PHP
equivalent) as well as assets rendered with Assetic.

For example, suppose you have the following:

.. configuration-block::

.. code-block:: html+twig

<img src="{{ asset('images/logo.png') }}" alt="Symfony!" />

.. code-block:: php
<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>" alt="Symfony!" />
By default, this will render a path to your image such as ``/images/logo.png``.
Now, activate the ``version`` option:

.. configuration-block::

.. code-block:: yaml
# app/config/config.yml
framework:
# ...
assets:
version: 'v2'
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:assets version="v2">
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
// ...
'assets' => array(
'version' => 'v2',
),
));
Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use
this feature, you **must** manually increment the ``version`` value
before each deployment so that the query parameters change.

It's also possible to set the version value on an asset-by-asset basis (instead
of using the global version - e.g. ``v2`` - set here). See
:ref:`Versioning by Asset <book-templating-version-by-asset>` for details.

You can also control how the query string works via the `version_format`_
option.

.. tip::

As with all settings, you can use a parameter as value for the
``version``. This makes it easier to increment the cache on each
deployment.

.. _reference-templating-version-format:
.. _reference-assets-version-format:

version_format
..............

**type**: ``string`` **default**: ``%%s?%%s``

This specifies a :phpfunction:`sprintf` pattern that will be used with the
`version`_ option to construct an asset's path. By default, the pattern
adds the asset's version as a query string. For example, if
``version_format`` is set to ``%%s?version=%%s`` and ``version``
is set to ``5``, the asset's path would be ``/images/logo.png?version=5``.

.. note::

All percentage signs (``%``) in the format string must be doubled to
escape the character. Without escaping, values might inadvertently be
interpreted as :ref:`book-service-container-parameters`.

.. tip::

Some CDN's do not support cache-busting via query strings, so injecting
the version into the actual file path is necessary. Thankfully,
``version_format`` is not limited to producing versioned query
strings.

The pattern receives the asset's original path and version as its first
and second parameters, respectively. Since the asset's path is one
parameter, you cannot modify it in-place (e.g. ``/images/logo-v5.png``);
however, you can prefix the asset's path using a pattern of
``version-%%2$s/%%1$s``, which would result in the path
``version-5/images/logo.png``.

URL rewrite rules could then be used to disregard the version prefix
before serving the asset. Alternatively, you could copy assets to the
appropriate version path as part of your deployment process and forgot
any URL rewriting. The latter option is useful if you would like older
asset versions to remain accessible at their original URL.

templating
~~~~~~~~~~

Expand Down

0 comments on commit cc12d7f

Please sign in to comment.