Skip to content

Commit 40dff64

Browse files
javiereguiluzjaviereguiluz
committed
Minor updates to the doc and service config
1 parent 80d0ca2 commit 40dff64

File tree

1 file changed

+104
-119
lines changed

1 file changed

+104
-119
lines changed

‎cookbook/asset/custom_version_strategy.rst‎

Lines changed: 104 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -19,92 +19,108 @@ Symfony supports the basic asset versioning thanks to the
1919
options. If your application requires a more advanced versioning, you can create
2020
your own version strategy.
2121

22-
Default Package
23-
---------------
22+
Creating your Own Asset Version Strategy
23+
----------------------------------------
2424

25-
The default package is used when you do not specify a package name in the
26-
:ref:`asset <reference-twig-function-asset>` Twig function. In order to
27-
override the version strategy used by the default package, it is necessary
28-
to add a compiler pass.
25+
The following example shows how to create a version strategy compatible with
26+
`gulp-buster`_. This tool defines a configuration file called ``busters.json``
27+
which maps each asset file to its content hash:
2928

30-
This example shows how to integrate with `gulp-buster`_.
29+
.. code-block:: json
3130
32-
.. note::
31+
{
32+
"js/script.js": "f9c7afd05729f10f55b689f36bb20172",
33+
"css/style.css": "91cd067f79a5839536b46c494c4272d8"
34+
}
3335
34-
busters.json as referenced below is the output from gulp-buster which
35-
maps each asset file to its hash. A small snippet of the file's format
36-
(JSON object):
36+
Implement VersionStrategyInterface
37+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3738

38-
.. code-block:: json
39+
Asset version strategies are PHP classes that implement the
40+
:class:`Symfony\\Component\\Asset\\VersionStrategy\\VersionStrategyInterface`.
41+
In this example, the constructor of the class takes as arguments the path to
42+
the manifest file generated by gulp-buster and the format of the generated
43+
version string::
3944

40-
{
41-
"js/script.js": "f9c7afd05729f10f55b689f36bb20172",
42-
"css/style.css": "91cd067f79a5839536b46c494c4272d8"
43-
}
45+
// src/AppBundle/Asset/VersionStrategy/GulpBusterVersionStrategy.php
46+
namespace AppBundle\Asset\VersionStrategy;
4447

45-
Create Compiler Pass
46-
~~~~~~~~~~~~~~~~~~~~
48+
use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;
4749

48-
.. code-block:: php
50+
class GulpBusterVersionStrategy implements VersionStrategyInterface
51+
{
52+
/**
53+
* @var string
54+
*/
55+
private $manifestPath;
4956

50-
// src/AppBundle/DependencyInjection/Compiler/OverrideAssetsDefaultPackagePass.php
51-
namespace AppBundle\DependencyInjection\Compiler;
57+
/**
58+
* @var string
59+
*/
60+
private $format;
5261

53-
use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
54-
use Symfony\Component\DependencyInjection\ContainerBuilder;
55-
use Symfony\Component\DependencyInjection\Reference;
62+
/**
63+
* @var string[]
64+
*/
65+
private $hashes;
5666

57-
class OverrideAssetsDefaultPackagePass implements CompilerPassInterface
58-
{
59-
public function process(ContainerBuilder $container)
67+
/**
68+
* @param string $manifestPath
69+
* @param string|null $format
70+
*/
71+
public function __construct($manifestPath, $format = null)
6072
{
61-
$definition = $container->getDefinition('assets._default_package');
62-
$definition->replaceArgument(1, new Reference('app.assets.buster_version_strategy'));
73+
$this->manifestPath = $manifestPath;
74+
$this->format = $format ?: '%s?%s';
6375
}
64-
}
6576

66-
The code above fetches the service definition of the default package, and replaces
67-
its second argument (the version strategy).
77+
public function getVersion($path)
78+
{
79+
if (!is_array($this->hashes)) {
80+
$this->hashes = $this->loadManifest();
81+
}
82+
83+
return isset($this->hashes[$path]) ? $this->hashes[$path] : '';
84+
}
6885

69-
Register Compiler Pass
70-
~~~~~~~~~~~~~~~~~~~~~~
86+
public function applyVersion($path)
87+
{
88+
$version = $this->getVersion($path);
7189

72-
.. code-block:: php
90+
if ('' === $version) {
91+
return $path;
92+
}
7393

74-
// src/AppBundle/AppBundle.php
75-
namespace AppBundle;
94+
$versionized = sprintf($this->format, ltrim($path, '/'), $version);
7695

77-
use AppBundle\DependencyInjection\Compiler\OverrideAssetsDefaultPackagePass;
78-
use Symfony\Component\DependencyInjection\ContainerBuilder;
79-
use Symfony\Component\HttpKernel\Bundle\Bundle;
96+
if ($path && '/' === $path[0]) {
97+
return '/'.$versionized;
98+
}
8099

81-
class AppBundle extends Bundle
82-
{
83-
public function build(ContainerBuilder $container)
100+
return $versionized;
101+
}
102+
103+
private function loadManifest(array $options)
84104
{
85-
parent::build($container);
105+
$hashes = json_decode(file_get_contents($this->manifestPath), true);
86106

87-
// only register in prod environment
88-
if ('prod' === $container->getParameter('kernel.environment')) {
89-
$container->addCompilerPass(new OverrideAssetsDefaultPackagePass());
90-
}
107+
return $hashes;
91108
}
92109
}
93110

94-
See :doc:`/cookbook/service_container/compiler_passes` for more information
95-
on how to use compiler passes.
111+
Register the Strategy Service
112+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
96113

97-
Register Services
98-
~~~~~~~~~~~~~~~~~
114+
After creating the strategy PHP class, register it as a Symfony service
99115

100116
.. configuration-block::
101117

102118
.. code-block:: yaml
103119
104120
# app/config/services.yml
105121
services:
106-
app.assets.buster_version_strategy:
107-
class: AppBundle\Asset\VersionStrategy\BusterVersionStrategy
122+
app.assets.versioning.gulp_buster:
123+
class: AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy
108124
arguments:
109125
- "%kernel.root_dir%/../busters.json"
110126
- "%%s?version=%%s"
@@ -120,7 +136,8 @@ Register Services
120136
http://symfony.com/schema/dic/services/services-1.0.xsd"
121137
>
122138
<services>
123-
<service id="app.assets.buster_version_strategy" class="AppBundle\Asset\VersionStrategy\BusterVersionStrategy" public="false">
139+
<service id="app.assets.versioning.gulp_buster"
140+
class="AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy" public="false">
124141
<argument>%kernel.root_dir%/../busters.json</argument>
125142
<argument>%%s?version=%%s</argument>
126143
</service>
@@ -133,85 +150,53 @@ Register Services
133150
use Symfony\Component\DependencyInjection\Definition;
134151
135152
$definition = new Definition(
136-
'AppBundle\Asset\VersionStrategy\BusterVersionStrategy',
153+
'AppBundle\Asset\VersionStrategy\GulpBusterVersionStrategy',
137154
array(
138155
'%kernel.root_dir%/../busters.json',
139156
'%%s?version=%%s',
140157
)
141158
);
142159
$definition->setPublic(false);
143160
144-
$container->setDefinition('app.assets.buster_version_strategy', $definition);
145-
146-
Implement VersionStrategyInterface
147-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
161+
$container->setDefinition('app.assets.versioning.gulp_buster', $definition);
148162
149-
.. code-block:: php
163+
Finally, enable the new asset versioning for all the application assets or just
164+
for some :ref:`asset package <reference-framework-assets-packages>` thanks to
165+
the :ref:`version_strategy <reference-framework-assets-version_strategy>` option:
150166

151-
// src/AppBundle/Asset/VersionStrategy/BusterVersionStrategy.php
152-
namespace AppBundle\Asset\VersionStrategy;
153-
154-
use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;
155-
156-
class BusterVersionStrategy implements VersionStrategyInterface
157-
{
158-
/**
159-
* @var string
160-
*/
161-
private $manifestPath;
162-
163-
/**
164-
* @var string
165-
*/
166-
private $format;
167-
168-
/**
169-
* @var string[]
170-
*/
171-
private $hashes;
172-
173-
/**
174-
* @param string $manifestPath
175-
* @param string|null $format
176-
*/
177-
public function __construct($manifestPath, $format = null)
178-
{
179-
$this->manifestPath = $manifestPath;
180-
$this->format = $format ?: '%s?%s';
181-
}
182-
183-
public function getVersion($path)
184-
{
185-
if (!is_array($this->hashes)) {
186-
$this->hashes = $this->loadManifest();
187-
}
188-
189-
return isset($this->hashes[$path]) ? $this->hashes[$path] : '';
190-
}
167+
.. configuration-block::
191168

192-
public function applyVersion($path)
193-
{
194-
$version = $this->getVersion($path);
169+
.. code-block:: yaml
195170
196-
if ('' === $version) {
197-
return $path;
198-
}
171+
# app/config/config.yml
172+
framework:
173+
# ...
174+
assets:
175+
version_strategy: 'app.assets.versioning.gulp_buster'
199176
200-
$versionized = sprintf($this->format, ltrim($path, '/'), $version);
177+
.. code-block:: xml
201178
202-
if ($path && '/' === $path[0]) {
203-
return '/'.$versionized;
204-
}
179+
<!-- app/config/config.xml -->
180+
<?xml version="1.0" encoding="UTF-8" ?>
181+
<container xmlns="http://symfony.com/schema/dic/services"
182+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
183+
xmlns:framework="http://symfony.com/schema/dic/symfony"
184+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
185+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
205186
206-
return $versionized;
207-
}
187+
<framework:config>
188+
<framework:assets version_strategy="app.assets.versioning.gulp_buster" />
189+
</framework:config>
190+
</container>
208191
209-
private function loadManifest(array $options)
210-
{
211-
$hashes = json_decode(file_get_contents($this->manifestPath), true);
192+
.. code-block:: php
212193
213-
return $hashes;
214-
}
215-
}
194+
// app/config/config.php
195+
$container->loadFromExtension('framework', array(
196+
// ...
197+
'assets' => array(
198+
'version_strategy' => 'app.assets.versioning.gulp_buster',
199+
),
200+
));
216201
217202
.. _`gulp-buster`: https://www.npmjs.com/package/gulp-buster

0 commit comments

Comments
 (0)