From cd0efedfb5b91ab27158c973f81269c4f537778a Mon Sep 17 00:00:00 2001 From: Henry Snoek Date: Wed, 20 Jan 2016 22:01:53 +0100 Subject: [PATCH 1/7] [WIP] moving assets version and version_format options under assets section --- book/templating.rst | 4 +- cookbook/assetic/asset_management.rst | 2 +- reference/configuration/assetic.rst | 2 +- reference/configuration/framework.rst | 62 ++++++++++++++++----------- reference/twig_reference.rst | 2 +- 5 files changed, 42 insertions(+), 30 deletions(-) diff --git a/book/templating.rst b/book/templating.rst index bb41b86ef55..2aebd8ccbaf 100644 --- a/book/templating.rst +++ b/book/templating.rst @@ -1064,7 +1064,7 @@ being used and generating the correct paths accordingly. Additionally, if you use the ``asset`` function, Symfony can automatically append a query string to your asset, in order to guarantee that updated static assets won't be cached when deployed. For example, ``/images/logo.png`` might -look like ``/images/logo.png?v2``. For more information, see the :ref:`ref-framework-assets-version` +look like ``/images/logo.png?v2``. For more information, see the :ref:`reference-framework-assets-version` configuration option. .. _`book-templating-version-by-asset`: @@ -1088,7 +1088,7 @@ if you are using Twig (or the fourth argument if you are using PHP) to the desir ) ?>" alt="Symfony!" /> If you don't give a version or pass ``null``, the default package version -(from :ref:`ref-framework-assets-version`) will be used. If you pass ``false``, +(from :ref:`reference-framework-assets-version`) will be used. If you pass ``false``, versioned URL will be deactivated for this asset. If you need absolute URLs for assets, you can set the ``absolute`` argument diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst index 9cd09d3f11c..db06caf0aea 100644 --- a/cookbook/assetic/asset_management.rst +++ b/cookbook/assetic/asset_management.rst @@ -472,7 +472,7 @@ done from the template and is relative to the public document root: Symfony also contains a method for cache *busting*, where the final URL generated by Assetic contains a query parameter that can be incremented via configuration on each deployment. For more information, see the - :ref:`ref-framework-assets-version` configuration option. + :ref:`reference-framework-assets-version` configuration option. .. _cookbook-assetic-dumping: diff --git a/reference/configuration/assetic.rst b/reference/configuration/assetic.rst index 1b45dd43502..45b300331f9 100644 --- a/reference/configuration/assetic.rst +++ b/reference/configuration/assetic.rst @@ -50,7 +50,7 @@ Full Default Configuration some_filter: [] workers: # see https://github.com/symfony/AsseticBundle/pull/119 - # Cache can also be busted via the framework.templating.assets_version + # Cache can also be busted via the framework.assets.version # setting - see the "framework" configuration section cache_busting: enabled: false diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 97989c67b76..3391bd1a0cb 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -69,9 +69,10 @@ Configuration * `gc_probability`_ * `gc_maxlifetime`_ * `save_path`_ +* `assets`_ + * `version`_ + * `version_format`_ * `templating`_ - * `assets_version`_ - * `assets_version_format`_ * `hinclude_default_template`_ * :ref:`form ` * `resources`_ @@ -850,14 +851,13 @@ setting the value to ``null``: ), )); -templating -~~~~~~~~~~ +assets +~~~~~~ .. _reference-framework-assets-version: -.. _ref-framework-assets-version: -assets_version -.............. +version +....... **type**: ``string`` @@ -879,7 +879,7 @@ For example, suppose you have the following: Symfony! By default, this will render a path to your image such as ``/images/logo.png``. -Now, activate the ``assets_version`` option: +Now, activate the ``version`` option: .. configuration-block:: @@ -888,7 +888,10 @@ Now, activate the ``assets_version`` option: # app/config/config.yml framework: # ... - templating: { engines: ['twig'], assets_version: v2 } + assets: + version: 'v2' + templating: + engines: ['twig'] .. code-block:: xml @@ -900,7 +903,8 @@ Now, activate the ``assets_version`` option: 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"> - + + twig @@ -911,40 +915,42 @@ Now, activate the ``assets_version`` option: // app/config/config.php $container->loadFromExtension('framework', array( // ... - 'templating' => array( - 'engines' => array('twig'), - 'assets_version' => 'v2', + 'assets' => array( + 'version' => 'v2', + ), + 'templating' => array( + 'engines' => array('twig'), ), )); Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use -this feature, you **must** manually increment the ``assets_version`` value +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 ` for details. -You can also control how the query string works via the `assets_version_format`_ +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 - ``assets_version``. This makes it easier to increment the cache on each + ``version``. This makes it easier to increment the cache on each deployment. -.. _reference-templating-version-format: +.. _reference-assets-version-format: -assets_version_format -..................... +version_format +.............. **type**: ``string`` **default**: ``%%s?%%s`` This specifies a :phpfunction:`sprintf` pattern that will be used with the -`assets_version`_ option to construct an asset's path. By default, the pattern +`version`_ option to construct an asset's path. By default, the pattern adds the asset's version as a query string. For example, if -``assets_version_format`` is set to ``%%s?version=%%s`` and ``assets_version`` +``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:: @@ -957,7 +963,7 @@ is set to ``5``, the asset's path would be ``/images/logo.png?version=5``. Some CDN's do not support cache-busting via query strings, so injecting the version into the actual file path is necessary. Thankfully, - ``assets_version_format`` is not limited to producing versioned query + ``version_format`` is not limited to producing versioned query strings. The pattern receives the asset's original path and version as its first @@ -973,6 +979,9 @@ is set to ``5``, the asset's path would be ``/images/logo.png?version=5``. any URL rewriting. The latter option is useful if you would like older asset versions to remain accessible at their original URL. +templating +~~~~~~~~~~ + hinclude_default_template ......................... @@ -1277,7 +1286,7 @@ Each package can configure the following options: * :ref:`base_urls ` * :ref:`version ` -* :ref:`version_format ` +* :ref:`version_format ` translator ~~~~~~~~~~ @@ -1589,10 +1598,13 @@ Full Default Configuration serializer: enabled: false + # assets configuration + assets: + version: ~ + version_format: '%%s?%%s' + # templating configuration templating: - assets_version: ~ - assets_version_format: '%%s?%%s' hinclude_default_template: ~ form: resources: diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst index 8fd0c083ec9..16241ebccd0 100644 --- a/reference/twig_reference.rst +++ b/reference/twig_reference.rst @@ -111,7 +111,7 @@ asset Returns a public path to ``path``, which takes into account the base path set for the package and the URL path. More information in -:ref:`book-templating-assets`. For asset versioning, see :ref:`ref-framework-assets-version`. +:ref:`book-templating-assets`. For asset versioning, see :ref:`reference-framework-assets-version`. assets_version ~~~~~~~~~~~~~~ From 46156f4920dd040a64adab5d90fc2f289babe25e Mon Sep 17 00:00:00 2001 From: Henry Snoek Date: Mon, 15 Feb 2016 13:25:25 +0100 Subject: [PATCH 2/7] put anchor back --- reference/configuration/framework.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 3391bd1a0cb..2f280593ac4 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -855,6 +855,7 @@ assets ~~~~~~ .. _reference-framework-assets-version: +.. _ref-framework-assets-version: version ....... From 5969b80c7e524a88e461f94cc1696b1d5575b764 Mon Sep 17 00:00:00 2001 From: Henry Snoek Date: Tue, 16 Feb 2016 20:56:47 +0100 Subject: [PATCH 3/7] move packages and base_urls to assets section remove templating config from examples put anchor back --- reference/configuration/framework.rst | 331 ++++++++++---------------- 1 file changed, 126 insertions(+), 205 deletions(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 2f280593ac4..a771332379c 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -72,17 +72,15 @@ Configuration * `assets`_ * `version`_ * `version_format`_ + * `base_urls`_ + * `packages`_ * `templating`_ * `hinclude_default_template`_ * :ref:`form ` * `resources`_ - * `assets_base_urls`_ - * http - * ssl * :ref:`cache ` * `engines`_ * `loaders`_ - * `packages`_ * `translator`_ * :ref:`enabled ` * `fallbacks`_ @@ -891,8 +889,6 @@ Now, activate the ``version`` option: # ... assets: version: 'v2' - templating: - engines: ['twig'] .. code-block:: xml @@ -905,10 +901,6 @@ Now, activate the ``version`` option: http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> - - - twig - .. code-block:: php @@ -919,9 +911,6 @@ Now, activate the ``version`` option: 'assets' => array( 'version' => 'v2', ), - 'templating' => array( - 'engines' => array('twig'), - ), )); Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use @@ -941,6 +930,7 @@ option. ``version``. This makes it easier to increment the cache on each deployment. +.. _reference-templating-version-format: .. _reference-assets-version-format: version_format @@ -980,37 +970,57 @@ is set to ``5``, the asset's path would be ``/images/logo.png?version=5``. any URL rewriting. The latter option is useful if you would like older asset versions to remain accessible at their original URL. -templating -~~~~~~~~~~ +.. _reference-templating-base-urls: +.. _reference-assets-base-urls: -hinclude_default_template -......................... +base_urls +......... -**type**: ``string`` **default**: ``null`` +**type**: ``array`` -Sets the content shown during the loading of the fragment or when JavaScript -is disabled. This can be either a template name or the content itself. +This option allows you to define base URLs to be used for assets. +If multiple base URLs are provided, Symfony will select one from the +collection each time it generates an asset's path: -.. seealso:: +.. configuration-block:: - See :ref:`book-templating-hinclude` for more information about hinclude. + .. code-block:: yaml -.. _reference-templating-form: + # app/config/config.yml + framework: + # ... + assets: + base_urls: + - 'http://cdn.example.com/' -form -.... + .. code-block:: xml -resources -""""""""" + + + -**type**: ``string[]`` **default**: ``['FrameworkBundle:Form']`` + + -A list of all resources for form theming in PHP. This setting is not required -if you're using the Twig format for your templates, in that case refer to -:ref:`the form book chapter `. + + + -Assume you have custom global form themes in -``src/WebsiteBundle/Resources/views/Form``, you can configure this like: + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + // ... + 'assets' => array( + 'base_urls' => array('http://cdn.example.com/'), + ), + )); + +packages +........ + +You can group assets into packages, to specify different base URLs for them: .. configuration-block:: @@ -1018,10 +1028,11 @@ Assume you have custom global form themes in # app/config/config.yml framework: - templating: - form: - resources: - - 'WebsiteBundle:Form' + # ... + assets: + packages: + avatars: + base_urls: 'http://static_cdn.example.com/avatars' .. code-block:: xml @@ -1035,15 +1046,13 @@ Assume you have custom global form themes in - - - + - WebsiteBundle:Form + - - - + @@ -1052,92 +1061,65 @@ Assume you have custom global form themes in // app/config/config.php $container->loadFromExtension('framework', array( - 'templating' => array( - 'form' => array( - 'resources' => array( - 'WebsiteBundle:Form' + // ... + 'assets' => array( + 'packages' => array( + 'avatars' => array( + 'base_urls' => 'http://static_cdn.example.com/avatars', ), ), ), )); -.. note:: +Now you can use the ``avatars`` package in your templates: - The default form templates from ``FrameworkBundle:Form`` will always - be included in the form resources. +.. configuration-block:: php -.. seealso:: + .. code-block:: html+twig - See :ref:`book-forms-theming-global` for more information. + -.. _reference-templating-base-urls: + .. code-block:: html+php -assets_base_urls -................ + -**default**: ``{ http: [], ssl: [] }`` +Each package can configure the following options: -This option allows you to define base URLs to be used for assets referenced -from ``http`` and ``ssl`` (``https``) pages. If multiple base URLs are -provided, Symfony will select one from the collection each time it generates -an asset's path: +* :ref:`base_urls ` +* :ref:`version ` +* :ref:`version_format ` -.. configuration-block:: +templating +~~~~~~~~~~ - .. code-block:: yaml +hinclude_default_template +......................... - # app/config/config.yml - framework: - # ... - templating: - assets_base_urls: - http: - - 'http://cdn.example.com/' - # you can also pass just a string: - # assets_base_urls: - # http: '//cdn.example.com/' +**type**: ``string`` **default**: ``null`` - .. code-block:: xml +Sets the content shown during the loading of the fragment or when JavaScript +is disabled. This can be either a template name or the content itself. - - - +.. seealso:: - - + See :ref:`book-templating-hinclude` for more information about hinclude. - - - http://cdn.example.com/ - - - - +.. _reference-templating-form: - .. code-block:: php +form +.... - // app/config/config.php - $container->loadFromExtension('framework', array( - // ... - 'templating' => array( - 'assets_base_urls' => array( - 'http' => array( - 'http://cdn.example.com/', - ), - ), - // you can also pass just a string: - // 'assets_base_urls' => array( - // 'http' => '//cdn.example.com/', - // ), - ), - )); +resources +""""""""" -For your convenience, you can pass a string or array of strings to -``assets_base_urls`` directly. This will automatically be organized into -the ``http`` and ``ssl`` base urls (``https://`` and `protocol-relative`_ -URLs will be added to both collections and ``http://`` only to the ``http`` -collection): +**type**: ``string[]`` **default**: ``['FrameworkBundle:Form']`` + +A list of all resources for form theming in PHP. This setting is not required +if you're using the Twig format for your templates, in that case refer to +:ref:`the form book chapter `. + +Assume you have custom global form themes in +``src/WebsiteBundle/Resources/views/Form``, you can configure this like: .. configuration-block:: @@ -1145,26 +1127,33 @@ collection): # app/config/config.yml framework: - # ... templating: - assets_base_urls: - - '//cdn.example.com/' - # you can also pass just a string: - # assets_base_urls: '//cdn.example.com/' + form: + resources: + - 'WebsiteBundle:Form' .. code-block:: xml + 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"> - - //cdn.example.com/ + + + + WebsiteBundle:Form + + + + @@ -1172,16 +1161,24 @@ collection): // app/config/config.php $container->loadFromExtension('framework', array( - // ... 'templating' => array( - 'assets_base_urls' => array( - '//cdn.example.com/', + 'form' => array( + 'resources' => array( + 'WebsiteBundle:Form' + ), ), - // you can also pass just a string: - // 'assets_base_urls' => '//cdn.example.com/', ), )); +.. note:: + + The default form templates from ``FrameworkBundle:Form`` will always + be included in the form resources. + +.. seealso:: + + See :ref:`book-forms-theming-global` for more information. + .. _reference-templating-cache: cache @@ -1217,78 +1214,6 @@ templating loaders. Templating loaders are used to find and load templates from a resource (e.g. a filesystem or database). Templating loaders must implement :class:`Symfony\\Component\\Templating\\Loader\\LoaderInterface`. -packages -........ - -You can group assets into packages, to specify different base URLs for them: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - framework: - # ... - templating: - packages: - avatars: - base_urls: 'http://static_cdn.example.com/avatars' - - .. code-block:: xml - - - - - - - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('framework', array( - // ... - 'templating' => array( - 'packages' => array( - 'avatars' => array( - 'base_urls' => 'http://static_cdn.example.com/avatars', - ), - ), - ), - )); - -Now you can use the ``avatars`` package in your templates: - -.. configuration-block:: php - - .. code-block:: html+twig - - - - .. code-block:: html+php - - - -Each package can configure the following options: - -* :ref:`base_urls ` -* :ref:`version ` -* :ref:`version_format ` - translator ~~~~~~~~~~ @@ -1603,6 +1528,14 @@ Full Default Configuration assets: version: ~ version_format: '%%s?%%s' + base_urls: [] + packages: + + # Prototype + name: + version: ~ + version_format: '%%s?%%s' + base_urls: [] # templating configuration templating: @@ -1612,24 +1545,12 @@ Full Default Configuration # Default: - FrameworkBundle:Form - assets_base_urls: - http: [] - ssl: [] cache: ~ engines: # Required # Example: - twig loaders: [] - packages: - - # Prototype - name: - version: ~ - version_format: '%%s?%%s' - base_urls: - http: [] - ssl: [] # translator configuration translator: From 61403e74a1077d5921c16064fe0dde64903ad3ca Mon Sep 17 00:00:00 2001 From: Henry Snoek Date: Tue, 16 Feb 2016 21:01:24 +0100 Subject: [PATCH 4/7] remove unused reference --- reference/configuration/framework.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index a771332379c..ec5c4f345bc 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -1571,7 +1571,6 @@ Full Default Configuration file_cache_dir: '%kernel.cache_dir%/annotations' debug: '%kernel.debug%' -.. _`protocol-relative`: http://tools.ietf.org/html/rfc3986#section-4.2 .. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html .. _`Security Advisory Blog post`: https://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released#cve-2013-4752-request-gethost-poisoning .. _`Doctrine Cache`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html From cc12d7f5aac53a956acced92673f1093152eaa80 Mon Sep 17 00:00:00 2001 From: Henry Snoek Date: Sat, 20 Feb 2016 09:10:11 +0100 Subject: [PATCH 5/7] change order of assets configuration options --- reference/configuration/framework.rst | 240 +++++++++++++------------- 1 file changed, 120 insertions(+), 120 deletions(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index ec5c4f345bc..236c650cc13 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -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 ` @@ -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 - - Symfony! - - .. code-block:: php - - 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 - - - - - - - - - .. 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 ` 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: @@ -1089,6 +971,124 @@ Each package can configure the following options: * :ref:`version ` * :ref:`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 + + Symfony! + + .. code-block:: php + + 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 + + + + + + + + + .. 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 ` 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 ~~~~~~~~~~ From 5d06eb533cf9af94ae06c521d47095b7c3248f32 Mon Sep 17 00:00:00 2001 From: Henry Snoek Date: Sat, 20 Feb 2016 09:28:50 +0100 Subject: [PATCH 6/7] document base_path option --- reference/configuration/framework.rst | 50 +++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 236c650cc13..95fdce628f0 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -70,6 +70,7 @@ Configuration * `gc_maxlifetime`_ * `save_path`_ * `assets`_ + * `base_path`_ * `base_urls`_ * `packages`_ * `version`_ @@ -852,6 +853,48 @@ setting the value to ``null``: assets ~~~~~~ +.. _reference-assets-base-path: + +base_path +......... + +**type**: ``string`` + +This option allows you to define a base path to be used for assets: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + # ... + assets: + base_path: '/images' + + .. code-block:: xml + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + // ... + 'assets' => array( + 'base_path' => '/images', + ), + )); + .. _reference-templating-base-urls: .. _reference-assets-base-urls: @@ -967,6 +1010,7 @@ Now you can use the ``avatars`` package in your templates: Each package can configure the following options: +* :ref:`base_path ` * :ref:`base_urls ` * :ref:`version ` * :ref:`version_format ` @@ -1526,16 +1570,18 @@ Full Default Configuration # assets configuration assets: + base_path: ~ + base_urls: [] version: ~ version_format: '%%s?%%s' - base_urls: [] packages: # Prototype name: + base_path: ~ + base_urls: [] version: ~ version_format: '%%s?%%s' - base_urls: [] # templating configuration templating: From 2a905d8c94b9abb41cb6d7925959873e6aa5262d Mon Sep 17 00:00:00 2001 From: Henry Snoek Date: Sat, 20 Feb 2016 09:47:09 +0100 Subject: [PATCH 7/7] small fixes for xml configuration examples --- reference/configuration/framework.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 95fdce628f0..d12fa008dcd 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -882,7 +882,9 @@ This option allows you to define a base path to be used for assets: 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"> - + + + .. code-block:: php @@ -923,11 +925,12 @@ collection each time it generates an asset's path: + 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"> - - @@ -970,15 +973,11 @@ You can group assets into packages, to specify different base URLs for them: http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> - - - + base-url="http://static_cdn.example.com/avatars" /> - @@ -1063,7 +1062,9 @@ Now, activate the ``version`` option: 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"> - + + + .. code-block:: php