The Asset Component

Asset Packages

The Asset component manages assets through packages. A package groups all the assets which share the same properties: versioning strategy, base path, CDN hosts, etc. In the following basic example, a package is created to manage assets without any versioning:

1
2
3
4
5
6
7

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy;

$package = new Package(new EmptyVersionStrategy());

echo $package->getUrl('/image.png');
// result: /image.png

Packages implement PackageInterface, which defines the following two methods:

getVersion()

Returns the asset version for an asset.

getUrl()

Returns an absolute or root-relative public path.

With a package, you can:

A) version the assets; B) set a common base path (e.g. /css) for the assets; C) configure a CDN for the assets

Versioned Assets

One of the main features of the Asset component is the ability to manage the versioning of the application's assets. Asset versions are commonly used to control how these assets are cached.

Instead of relying on a simple version mechanism, the Asset component allows you to define advanced versioning strategies via PHP classes. The two built-in strategies are the EmptyVersionStrategy, which doesn't add any version to the asset and StaticVersionStrategy, which allows you to set the version with a format string.

In this example, the StaticVersionStrategy is used to append the v1 suffix to any asset path:

1
2
3
4
5
6
7

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy;

$package = new Package(new StaticVersionStrategy('v1'));

echo $package->getUrl('/image.png');
// result: /image.png?v1

In case you want to modify the version format, pass a sprintf-compatible format string as the second argument of the StaticVersionStrategy constructor:

1
2
3
4
5
6
7
8
9
10
11

// puts the 'version' word before the version value
$package = new Package(new StaticVersionStrategy('v1', '%s?version=%s'));

echo $package->getUrl('/image.png');
// result: /image.png?version=v1

// puts the asset version before its path
$package = new Package(new StaticVersionStrategy('v1', '%2$s/%1$s'));

echo $package->getUrl('/image.png');
// result: /v1/image.png

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;

class DateVersionStrategy implements VersionStrategyInterface
{
    private $version;

    public function __construct()
    {
        $this->version = date('Ymd');
    }

    public function getVersion($path)
    {
        return $this->version;
    }

    public function applyVersion($path)
    {
        return sprintf('%s?v=%s', $path, $this->getVersion($path));
    }
}

Grouped Assets

Often, many assets live under a common path (e.g. /static/images). If that's your case, replace the default Package class with PathPackage to avoid repeating that path over and over again:

1
2
3
4
5
6
7

use Symfony\Component\Asset\PathPackage;
// ...

$pathPackage = new PathPackage('/static/images', new StaticVersionStrategy('v1'));

echo $pathPackage->getUrl('/logo.png');
// result: /static/images/logo.png?v1

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\Asset\PathPackage;
use Symfony\Component\Asset\Context\RequestStackContext;
// ...

$pathPackage = new PathPackage(
    '/static/images',
    new StaticVersionStrategy('v1'),
    new RequestStackContext($requestStack)
);

echo $pathPackage->getUrl('/logo.png');
// result: /somewhere/static/images/logo.png?v1

Absolute Assets and CDNs

Applications that host their assets on different domains and CDNs (Content Delivery Networks) should use the UrlPackage class to generate absolute URLs for their assets:

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\Asset\UrlPackage;
// ...

$urlPackage = new UrlPackage(
    'http://static.example.com/images/',
    new StaticVersionStrategy('v1')
);

echo $urlPackage->getUrl('/logo.png');
// result: http://static.example.com/images/logo.png?v1

You can also pass a schema-agnostic URL:

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\Asset\UrlPackage;
// ...

$urlPackage = new UrlPackage(
    '//static.example.com/images/',
    new StaticVersionStrategy('v1')
);

echo $urlPackage->getUrl('/logo.png');
// result: //static.example.com/images/logo.png?v1

This is useful because assets will automatically be requested via HTTPS if a visitor is viewing your site in https. Just make sure that your CDN host supports https.

In case you serve assets from more than one domain to improve application performance, pass an array of URLs as the first argument to the UrlPackage constructor:

1
2
3
4
5
6
7
8
9
10
11
12
13

use Symfony\Component\Asset\UrlPackage;
// ...

$urls = array(
    '//static1.example.com/images/',
    '//static2.example.com/images/',
);
$urlPackage = new UrlPackage($urls, new StaticVersionStrategy('v1'));

echo $urlPackage->getUrl('/logo.png');
// result: http://static1.example.com/images/logo.png?v1
echo $urlPackage->getUrl('/icon.png');
// result: http://static2.example.com/images/icon.png?v1

For each asset, one of the URLs will be randomly used. But, the selection is deterministic, meaning that each asset will be always served by the same domain. This behavior simplifies the management of HTTP cache.

1
2
3
4
5
6
7
8
9
10
11
12
13

use Symfony\Component\Asset\UrlPackage;
use Symfony\Component\Asset\Context\RequestStackContext;
// ...

$urlPackage = new UrlPackage(
    array('http://example.com/', 'https://example.com/'),
    new StaticVersionStrategy('v1'),
    new RequestStackContext($requestStack)
);

echo $urlPackage->getUrl('/logo.png');
// assuming the RequestStackContext says that we are on a secure host
// result: https://example.com/logo.png?v1

Named Packages

Applications that manage lots of different assets may need to group them in packages with the same versioning strategy and base path. The Asset component includes a Packages class to simplify management of several packages.

In the following example, all packages use the same versioning strategy, but they all have different base paths:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\PathPackage;
use Symfony\Component\Asset\UrlPackage;
use Symfony\Component\Asset\Packages;
// ...

$versionStrategy = new StaticVersionStrategy('v1');

$defaultPackage = new Package($versionStrategy);

$namedPackages = array(
    'img' => new UrlPackage('http://img.example.com/', $versionStrategy),
    'doc' => new PathPackage('/somewhere/deep/for/documents', $versionStrategy),
);

$packages = new Packages($defaultPackage, $namedPackages);

The Packages class allows to define a default package, which will be applied to assets that don't define the name of package to use. In addition, this application defines a package named img to serve images from an external domain and a doc package to avoid repeating long paths when linking to a document inside a template:

1
2
3
4
5
6
7
8

echo $packages->getUrl('/main.css');
// result: /main.css?v1

echo $packages->getUrl('/logo.png', 'img');
// result: http://img.example.com/logo.png?v1

echo $packages->getUrl('/resume.pdf', 'doc');
// result: /somewhere/deep/for/documents/resume.pdf?v1