New in Symfony 2.7: the new Asset component

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.yml
framework:
    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.yml
framework:
    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 optional absolute 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.yml
framework:
    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.yml
framework:
    assets:
        version: 'v5'
        version_format: '%%s?version=%%s'
        packages:
            avatar:
                base_path: /img/avatars
            doc:
                base_path: /docs/pdf
                version_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.yml
framework:
    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 #}

Comments

Congrats with new component!
I think it will be useful for other frameworks, not only for Symfony.
1. Documentation in the templating section looks outdated http://symfony.com/doc/2.7/book/templating.html#linking-to-assets
2. Removing of the "version" argument and concatination it "by hand" is mush inconvenient. It is too hard apply custom version format now.
@Konstantin you are right about the outdated documentation. There are two pending pull requests to fix it:

https://github.com/symfony/symfony-docs/pull/5170
https://github.com/symfony/symfony-docs/pull/5171
There is a mistake in the example about Twig and the version for absolute URLs. Given that you use asset('logo.png'), the version is already added automatically. No need for adding it explicitly in this case
@Christophe thanks for pointing it. It's fixed now.
Great addition! Finally I can use the convenience of Symfony asset management with Silex, Lumen and custom PHP projects :)
Very helpfull component !
Why not rely on tools front-end developers are using like Grunt/Gulps instead? (Or in addition of Asset).
Totally agree with @Thomas Decaux. The Symfony Standard distribution (I don't think those things belong in the Symfony framework) needs to come with better support for frontend development workflow. That means replacing antiquated tools like Assetic with modern tools like Gulp and ideally Bower too (of course everyone has their own preferences but the point is Symfony Standard should come with a sensible end-to-end workflow).
wonderful component
how to pass current host in base_urls ?
in 2.6 i had:

base_urls: ~

and it worked, but now UrlPackage::getSslUrls throw an exception "" is not a valid URL

Comments are closed.

To ensure that comments stay relevant, they are closed for old posts.