Added "How to Use a Custom Version Strategy for Assets"

symfony · xabbuh · Dec 14, 2016 · Dec 13, 2016 · Dec 14, 2016 · d3308bee27ea45b7c36f0513e87c78b9ba1f940b
commit d3308bee27ea45b7c36f0513e87c78b9ba1f940b
diff --git a/frontend/custom_version_strategy.rst b/frontend/custom_version_strategy.rst
@@ -0,0 +1,200 @@
+.. index::
+   single: Asset; Custom Version Strategy
+
+How to Use a Custom Version Strategy for Assets
+===============================================
+
+.. versionadded:: 3.1
+    Support for custom version strategies was introduced in Symfony 3.1.
+
+Asset versioning is a technique that improves the performance of web
+applications by adding a version identifier to the URL of the static assets
+(CSS, JavaScript, images, etc.) When the content of the asset changes, its
+identifier is also modified to force the browser to download it again instead of
+reusing the cached asset.
+
+Symfony supports asset versioning thanks to the :ref:`version <reference-framework-assets-version>`
+and :ref:`version_format <reference-assets-version-format>` configuration
+options. If your application requires a more advanced versioning, such as
+generating the version dynamically based on some external information, you can
+create your own version strategy.
+
+Creating your Own Asset Version Strategy
+----------------------------------------
+
+The following example shows how to create a version strategy compatible with
+`gulp-buster`_. This tool defines a configuration file called ``busters.json``
+which maps each asset file to its content hash:
+
+.. code-block:: json
+
+    {
+        "js/script.js": "f9c7afd05729f10f55b689f36bb20172",
+        "css/style.css": "91cd067f79a5839536b46c494c4272d8"
+    }
+
+Implement VersionStrategyInterface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Asset version strategies are PHP classes that implement the
+:class:`Symfony\\Component\\Asset\\VersionStrategy\\VersionStrategyInterface`.
+In this example, the constructor of the class takes as arguments the path to
+the manifest file generated by `gulp-buster`_ and the format of the generated
+version string::
+
+    // src/AppBundle/Asset/VersionStrategy/GulpBusterVersionStrategy.php
+    namespace AppBundle\Asset\VersionStrategy;
+
+    use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;
+
+    class GulpBusterVersionStrategy implements VersionStrategyInterface
+    {
+        /**
+         * @var string
+         */
+        private $manifestPath;
+
+        /**
+         * @var string
+         */
+        private $format;
+
+        /**
+         * @var string[]
+         */
+        private $hashes;
+
+        /**
+         * @param string      $manifestPath
+         * @param string|null $format
+         */
+        public function __construct($manifestPath, $format = null)
+        {
+            $this->manifestPath = $manifestPath;
+            $this->format = $format ?: '%s?%s';
+        }
+
+        public function getVersion($path)
+        {
+            if (!is_array($this->hashes)) {
+                $this->hashes = $this->loadManifest();
+            }
+
+            return isset($this->hashes[$path]) ? $this->hashes[$path] : '';
+        }
+
+        public function applyVersion($path)
+        {
+            $version = $this->getVersion($path);
+
+            if ('' === $version) {
+                return $path;
+            }
+
+            $versionized = sprintf($this->format, ltrim($path, '/'), $version);
+
+            if ($path && '/' === $path[0]) {
+                return '/'.$versionized;
+            }
+
+            return $versionized;
+        }
+
+        private function loadManifest(array $options)
+        {
+            return json_decode(file_get_contents($this->manifestPath), true);
+        }
+    }
+
+Register the Strategy Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After creating the strategy PHP class, register it as a Symfony service.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            app.assets.versioning.gulp_buster:
+                class: AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy
+                arguments:
+                    - "%kernel.root_dir%/../busters.json"
+                    - "%%s?version=%%s"
+                public: false
+
+    .. code-block:: xml
+
+        <!-- app/config/services.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"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd"
+        >
+            <services>
+                <service id="app.assets.versioning.gulp_buster"
+                 class="AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy" public="false">
+                    <argument>%kernel.root_dir%/../busters.json</argument>
+                    <argument>%%s?version=%%s</argument>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        use Symfony\Component\DependencyInjection\Definition;
+
+        $definition = new Definition(
+            'AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy',
+            array(
+                '%kernel.root_dir%/../busters.json',
+                '%%s?version=%%s',
+            )
+        );
+        $definition->setPublic(false);
+
+        $container->setDefinition('app.assets.versioning.gulp_buster', $definition);
+
+Finally, enable the new asset versioning for all the application assets or just
+for some :ref:`asset package <reference-framework-assets-packages>` thanks to
+the :ref:`version_strategy <reference-assets-version-strategy>` option:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        framework:
+            # ...
+            assets:
+                version_strategy: 'app.assets.versioning.gulp_buster'
+
+    .. 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:config>
+                <framework:assets version-strategy="app.assets.versioning.gulp_buster" />
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('framework', array(
+            // ...
+            'assets' => array(
+                'version_strategy' => 'app.assets.versioning.gulp_buster',
+            ),
+        ));
+
+.. _`gulp-buster`: https://www.npmjs.com/package/gulp-buster
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -893,6 +893,8 @@ collection each time it generates an asset's path:
             ),
         ));
 
+.. _reference-framework-assets-packages:
+
 packages
 ........
 
@@ -963,22 +965,6 @@ Each package can configure the following options:
 * :ref:`version <reference-framework-assets-version>`
 * :ref:`version_format <reference-assets-version-format>`
 
-.. _reference-templating-version-strategy:
-.. _reference-assets-version-strategy:
-
-version_strategy
-................
-
-**type**: ``string`` **default**: ``null``
-
-This specifies the id of the service to use as the version strategy for
-all rendered asset paths. Version strategies must implement
-:class:`Symfony\\Component\\Asset\\VersionStrategy\\VersionStrategyInterface`.
-
-.. note::
-
-    This parameter cannot be set at the same time as ``version``.
-
 .. _reference-framework-assets-version:
 .. _ref-framework-assets-version:
 
@@ -1099,6 +1085,21 @@ 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.
 
+.. _reference-assets-version-strategy:
+.. _reference-templating-version-strategy:
+
+version_strategy
+................
+
+**type**: ``string`` **default**: ``null``
+
+The service id of the :doc:`asset version strategy </frontend/custom_version_strategy>`
+applied to the assets.
+
+.. note::
+
+    This parameter cannot be set at the same time as ``version``.
+
 templating
 ~~~~~~~~~~