|
| 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 |
0 commit comments