Contributed by
Fabien Potencier
in #13234.
Prior to Symfony 2.7, web asset management was done in the Templating component.
The design of that subsystem suffered from some errors (it required the request
scope because it relied on the Request instance) and limitations (for example in
the management of secure base URLs).
In order to solve those issues, Symfony 2.7 introduces a new component called Asset. Management of web assets is now decoupled from the Templating component, which allows to reuse it outside of Symfony (for example in the Silex microframework).
The new Asset component manages URL generation and versioning of web assets such as CSS stylesheets, JavaScript files and image files. This means that your templates become less verbose and your application is more flexible, because you can change the location and version of your assets just with a few minor changes in a configuration file.
Configuration changes¶
The old assets_* options defined under the templating section are now
defined under assets and their names have dropped the assets prefix. The
previous options are now deprecated (they will disappear in Symfony 3.0), but for
now the Asset component updates them automatically (you don't have to do any
change in your application configuration if you don't want to):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | # Symfony 2.6# app/config/config.ymlframework:templating:assets_version:'v5'assets_version_format:'%%s?version=%%s'assets_base_urls:http:['http://cdn.example.com']ssl:['https://secure.example.com']packages:# ...# Symfony 2.7# app/config/config.ymlframework:assets:version:'v5'version_format:'%%s?version=%%s'base_path:~base_urls:['http://cdn.example.com','https://secure.example.com']packages:# ... |
The only relevant change is introduced by the base_urls option, which no longer
separates regular (http) and secure (ssl) URLs.
Template function changes¶
In Symfony 2.7, the well-known asset() Twig function has removed the optionalabsolute and version arguments:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | {# Symfony 2.6 #}{{asset('logo.png',absolute=true)}}{# Symfony 2.7 #}{{absolute_url(asset('logo.png'))}}{# Symfony 2.6 #}{{asset('logo.png',version='v5')}}{# Symfony 2.7 (do nothing, version is automatically appended) #}{{asset('logo.png')}}{# use the asset_version() function if you need to output it manually #}{{asset_version('logo.png')}} |
Usage examples¶
Read the Asset component documentation to learn more about the features of this new component. You'll discover how to implement tricks like the following:
Define shortcuts for bundle assets¶
1 2 3 4 5 6 7 8 | # app/config/config.ymlframework:assets:packages:app:base_path:/bundles/app/img:base_path:/bundles/app/images/ |
1 2 3 4 5 | {{asset('images/me.png','app')}}{# /bundles/app/images/me.png #}{{asset('me.png','img')}}{# /bundles/app/images/me.png #} |
Advanced asset versioning¶
1 2 3 4 5 6 7 8 9 10 11 | # app/config/config.ymlframework:assets:version:'v5'version_format:'%%s?version=%%s'packages:avatar:base_path:/img/avatarsdoc:base_path:/docs/pdfversion_format:'%2$s/%1$s' |
1 2 3 4 5 | {{asset(user.uuid~'.png','avatar')}}{# /img/avatars/1b0ae6a5-1c39-4b49-bcc1-2a787c8ec139.png?version=v5 #}{{asset('contracts/signup.pdf','doc')}}{# /v5/docs/pdf/contracts/signup.pdf #} |
Context-aware CDNs¶
1 2 3 4 5 6 | # app/config/config.ymlframework:assets:base_urls:-'http://static1.example.com/images/'-'https://static2.example.com/images/' |
1 2 3 | {{asset('logo.png')}}{# in a regular page: http://static1.example.com/images/logo.png #}{# in a secure page: https://static2.example.com/images/logo.png #} |