8000 Added the documentation for the new Asset component · symfony/symfony-docs@6d367b1 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6d367b1

Browse files
javiereguiluzweaverryan
javiereguiluz
authored and
weaverryan
committed
Added the documentation for the new Asset component
1 parent 78733c3 commit 6d367b1

File tree

3 files changed

+254
-0
lines changed

3 files changed

+254
-0
lines changed

‎components/asset.rst

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
.. index::
2+
single: Asset
3+
single: Components; Asset
4+
5+
The Asset Component
6+
===================
7+
8+
The Asset manages URL generation and versioning for web assets such as CSS
9+
stylsheets, JavaScript files and image files.
10+
11+
Installation
12+
------------
13+
14+
You can install the component in two different ways:
15+
16+
* :doc:`Install it via Composer </components/using_components>` (``symfony/asset`` on `Packagist`_);
17+
* Use the official Git repository (https://github.com/symfony/Asset).
18+
19+
Usage
20+
-----
21+
22+
Asset Packages
23+
~~~~~~~~~~~~~~
24+
25+
The Asset component manages its assets through packages. A package groups all
26+
the assets which use the same versioning strategy. In the following basic
27+
example, a package is created to manage assets without any versioning:
28+
29+
.. code-block:: php
30+
31+
use Symfony\Component\Asset\Package;
32+
use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy;
33+
34+
$package = new Package(new EmptyVersionStrategy());
35+
36+
echo $package->getUrl('/image.png');
37+
// result: /image.png
38+
39+
Packages implement the ``PackageInterface``, which defines the following two
40+
methods::
41+
42+
namespace Symfony\Component\Asset;
43+
44+
interface PackageInterface
45+
{
46+
/**
47+
* Returns the asset version for an asset.
48+
*/
49+
public function getVersion($path);
50+
51+
/**
52+
* Returns an absolute or root-relative public path.
53+
*/
54+
public function getUrl($path);
55+
}
56+
57+
Versioned Assets
58+
~~~~~~~~~~~~~~~~
59+
60+
One of the main features of the Asset component is to manage the versioning of
61+
the application's assets. Asset versions are commonly used to control how these
62+
assets are cached.
63+
64+
Instead of relying on a simple version mechanism, the Asset component allows to
65+
define advanced version strategies via PHP classes. The two built-in strategies
66+
provided by the component are ``EmptyVersionStrategy``, which doesn't add any
67+
version to the asset, and ``StaticVersionStrategy``, which allows to set the
68+
version with a format string.
69+
70+
In this example, the ``StaticVersionStrategy`` is used to append the ``v1``
71+
suffix to any asset path::
72+
73+
use Symfony\Component\Asset\Package;
74+
use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy;
75+
76+
$package = new Package(new StaticVersionStrategy('v1'));
77+
78+
echo $package->getUrl('/image.png');
79+
// result: /image.png?v1
80+
81+
In case you want to modify the version format, pass a sprintf-compatible format
82+
string as the second argument of the ``StaticVersionStrategy`` constructor::
83+
84+
// put the 'version' word before the version value
85+
$package = new Package(new StaticVersionStrategy('v1', '%s?version=%s'));
86+
87+
echo $package->getUrl('/image.png');
88+
// result: /image.png?version=v1
89+
90+
// put the asset version before its path
91+
$package = new Package(new StaticVersionStrategy('v1', '%2$s/%1$s'));
92+
93+
echo $package->getUrl('/image.png');
94+
// result: /v1/image.png
95+
96+
Custom Version Strategies
97+
.........................
98+
99+
Use the ``VersionStrategyInterface`` to define your own version strategy. For
100+
example, you could define a versioning where the current date is appended to
101+
bust the cache every day::
102+
103+
use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;
104+
105+
class DateVersionStrategy implements VersionStrategyInterface
106+
{
107+
private $version;
108+
109+
public function __construct()
110+
{
111+
$this->version = date('Ymd');
112+
}
113+
114+
public function getVersion($path)
115+
{
116+
return $this->version;
117+
}
118+
119+
public function applyVersion($path)
120+
{
121+
return sprintf('%s?v=%s', $path, $this->getVersion($path));
122+
}
123+
}
124+
125+
Grouped Assets
126+
~~~~~~~~~~~~~~
127+
128+
It's common for applications to store their assets in a common path. If that's
129+
your case, replace the default ``Package`` class by ``PathPackage`` to avoid
130+
repeating the same path time and again::
131+
132+
use Symfony\Component\Asset\PathPackage;
133+
134+
$package = new PathPackage('/static/images', new StaticVersionStrategy('v1'));
135+
136+
echo $package->getUrl('/logo.png');
137+
// result: /static/images/logo.png?v1
138+
139+
Request Context Aware Assets
140+
............................
141+
142+
If you are also using the HttpFoundation component in your project, for example
143+
in a Symfony application, the ``PathPackage`` class can take into account the
144+
context of the current request::
145+
146+
use Symfony\Component\Asset\PathPackage;
147+
use Symfony\Component\Asset\Context\RequestStackContext;
148+
149+
$package = new PathPackage('/static/images', new StaticVersionStrategy('v1'));
150+
$package->setContext(new RequestStackContext($requestStack));
151+
152+
echo $package->getUrl('/logo.png');
153+
// result: /somewhere/static/images/logo.png?v1
154+
155+
When the request context is set, in addition to the configured base path,
156+
``PathPackage`` also prepends the current request base URL (``/somewhere/`` in
157+
this example) to assets. This allows your website to be hosted anywhere under
158+
the web server root directory.
159+
< 10000 /code>160+
Absolute Assets and CDNs
161+
~~~~~~~~~~~~~~~~~~~~~~~~
162+
163+
Applications that host their assets on different domains and CDNs (*Content
164+
Delivery Networks*) should use instead the ``UrlPackage`` class to generate
165+
absolute URLs for their assets::
166+
167+
use Symfony\Component\Asset\UrlPackage;
168+
169+
$package = new UrlPackage('http://static.example.com/images/', new StaticVersionStrategy('v1'));
170+
171+
echo $package->getUrl('/logo.png');
172+
// result: http://static.example.com/images/logo.png?v1
173+
174+
In case you serve assets from more than one domain to improve application
175+
performance, pass an array of URLs as the first argument of ``UrlPackage``
176+
constructor::
177+
178+
use Symfony\Component\Asset\UrlPackage;
179+
180+
$urls = array(
181+
'http://static1.example.com/images/',
182+
'http://static2.example.com/images/',
183+
);
184+
$package = new UrlPackage($urls, new StaticVersionStrategy('v1'));
185+
186+
echo $package->getUrl('/logo.png');
187+
// result: http://static1.example.com/images/logo.png?v1
188+
189+
The selection of the domain which will serve the asset is deterministic, meaning
190+
that each asset will be always served by the same domain. This behavior simplifies
191+
the management of HTTP cache.
192+
193+
Request Context Aware Assets
194+
............................
195+
196+
Similarly to application-relative assets, absolute assets can also take into
197+
account the context of the current request. In this case, only the request
198+
scheme is considered, in order to select the appropriate base URL (HTTPs or
199+
protocol-relative URLs for HTTPs requests, any base URL for HTTP requests)::
200+
201+
use Symfony\Component\Asset\UrlPackage;
202+
use Symfony\Component\Asset\Context\RequestStackContext;
203+
204+
$package = new UrlPackage(array('http://example.com/', 'https://example.com/'), new StaticVersionStrategy('v1'));
205+
$package->setContext(new RequestStackContext($requestStack));
206+
207+
echo $package->getUrl('/logo.png');
208+
// result: https://example.com/logo.png?v1
209+
210+
Named Packages
211+
~~~~~~~~~~~~~~
212+
213+
Applications that manage lots of different assets may need to group them in
214+
packages with the same versioning strategy and base path. The Asset component
215+
includes a ``Packages`` class to simplify the management of several packages.
216+
217+
In the following example, all packages use the same versioning strategy, but
218+
they all have different base paths::
219+
220+
use Symfony\Component\Asset\Package;
221+
use Symfony\Component\Asset\PathPackage;
222+
use Symfony\Component\Asset\UrlPackage;
223+
use Symfony\Component\Asset\Packages;
224+
225+
$versionStrategy = new StaticVersionStrategy('v1');
226+
227+
$defaultPackage = new Package($versionStrategy);
228+
229+
$namedPackages = array(
230+
'img' => new UrlPackage('http://img.example.com/', $versionStrategy),
231+
'doc' => new PathPackage('/somewhere/deep/for/documents', $versionStrategy),
232+
);
233+
234+
$packages = new Packages($defaultPackage, $namedPackages)
235+
236+
The ``Packages`` class requires to define a default package which will be applied
237+
to all assets except those which indicate the name of the package to use. In
238+
addition, this application defines a package named ``img`` to serve images from
239+
an external domain and a ``doc`` package to avoid repeating long paths when
240+
linking to a document inside a template::
241+
242+
echo $packages->getUrl('/main.css');
243+
// result: /main.css?v1
244+
245+
echo $packages->getUrl('/logo.png', 'img');
246+
// result: http://img.example.com/logo.png?v1
247+
248+
echo $packages->getUrl('/resume.pdf', 'doc');
249+
// result: /somewhere/deep/for/documents/resume.pdf?v1

‎components/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ The Components
55
:hidden:
66

77
using_components
8+
asset
89
class_loader/index
910
config/index
1011
console/index

‎components/map.rst.inc

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
* :doc:`/components/using_components`
22

3+
* **Asset**
4+
5+
* :doc:`/components/asset`
6+
37
* :doc:`/components/class_loader/index`
48

59
* :doc:`/components/class_loader/introduction`

0 commit comments

Comments
 (0)
0