Asset Component

The Asset component manages asset URLs.

Versioned Asset URLs

The basic Package adds a version to generated asset URLs:

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

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

echo $package->getUrl('/me.png');
// /me.png?v1

The default format can be configured:

$package = new Package(new StaticVersionStrategy('v1', '%s?version=%s'));

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

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

echo $package->getUrl('/me.png');
// /version-v1/me.png

Asset URLs Base Path

When all assets are stored in a common path, use the PathPackage to avoid repeating yourself:

use Symfony\Component\Asset\PathPackage;

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

echo $package->getUrl('/me.png');
// /images/me.png?v1

Asset URLs Base URLs

If your assets are hosted on different domain name than the main website, use the UrlPackage class:

use Symfony\Component\Asset\UrlPackage;

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

echo $package->getUrl('/me.png');
// http://assets.example.com/images/me.png?v1

One technique used to speed up page rendering in browsers is to use several domains for assets; this is possible by passing more than one base URLs:

use Symfony\Component\Asset\UrlPackage;

$urls = array(
    'http://a1.example.com/images/',
    'http://a2.example.com/images/',
);
$package = new UrlPackage($urls, new StaticVersionStrategy('v1'));

echo $package->getUrl('/me.png');
// http://a1.example.com/images/me.png?v1

Note that it's also guaranteed that any given path will always use the same base URL to be nice with HTTP caching mechanisms.

HttpFoundation Integration

If you are using HttpFoundation for your project, set the Context to get additional features for free:

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

$package = new PathPackage('images', new StaticVersionStrategy('v1'));
$package->setContext(new RequestStackContext($requestStack));

echo $package->getUrl('/me.png');
// /somewhere/images/me.png?v1

In addition to the configured base path, PathPackage now also automatically prepends the current request base URL to assets to allow your website to be hosted anywhere under the web server root directory.

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

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

echo $package->getUrl('/me.png');
// https://example.com/images/me.png?v1

UrlPackage now uses the current request scheme (HTTP or HTTPs) to select an appropriate base URL (HTTPs or protocol-relative URLs for HTTPs requests, any base URL for HTTP requests).

Named Packages

The Packages class allows to easily manages several packages in a single project by naming packages:

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

// by default, just add a version to all assets
$versionStrategy = new StaticVersionStrategy('v1');
$defaultPackage = new Asset\Package($versionStrategy);

$namedPackages = array(
    // images are hosted on another web server
    'img' => new Asset\UrlPackage('http://img.example.com/', $versionStrategy),

    // documents are stored deeply under the web root directory
    // let's create a shortcut
    'doc' => new Asset\PathPackage('/somewhere/deep/for/documents', $versionStrategy),
);

// bundle all packages to make it easy to use them
$packages = new Asset\Packages($defaultPackage, $namedPackages);

echo $packages->getUrl('/some.css');
// /some.css?v1

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

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

Resources

You can run the unit tests with the following command:

$ cd path/to/Symfony/Component/Asset/
$ composer update
$ phpunit