The Asset Component

The Asset component manages URL generation and versioning of web assets suchas CSS stylesheets, JavaScript files and image files.

In the past, it was common for web applications to hardcode URLs of web assets.For example:

<link rel="stylesheet" type="text/css" href="/css/main.css">
 
<!-- ... -->
 
<a href="/"><img src="/images/logo.png"></a>

This practice is no longer recommended unless the web application is extremelysimple. Hardcoding URLs can be a disadvantage because:

• Templates get verbose: you have to write the full path for eachasset. When using the Asset component, you can group assets in packages toavoid repeating the common part of their path;
• Versioning is difficult: it has to be custom managed for eachapplication. Adding a version (e.g. main.css?v=5) to the asset URLsis essential for some applications because it allows you to control howthe assets are cached. The Asset component allows you to define differentversioning strategies for each package;
• Moving assets' location is cumbersome and error-prone: it requires you tocarefully update the URLs of all assets included in all templates. The Assetcomponent allows to move assets effortlessly just by changing the base pathvalue associated with the package of assets;
• It's nearly impossible to use multiple CDNs: this technique requiresyou to change the URL of the asset randomly for each request. The Asset componentprovides out-of-the-box support for any number of multiple CDNs, both regular(http://) and secure (https://).

Installation

$ composer require symfony/asset

Note

If you install this component outside of a Symfony application, you mustrequire the vendor/autoload.php file in your code to enable the classautoloading mechanism provided by Composer. Readthis article for more details.

Usage

Asset Packages

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

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy;
 
$package = new Package(new EmptyVersionStrategy());
 
// Absolute path
echo $package->getUrl('/image.png');
// result: /image.png
 
// Relative path
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:

• version the assets;

• set a common base path (e.g. /css)for the assets;
• configure a CDN for the assets

Versioned Assets

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

Instead of relying on a simple version mechanism, the Asset component allowsyou to define advanced versioning strategies via PHP classes. The two built-instrategies 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 v1suffix to any asset path:

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy;
 
$package = new Package(new StaticVersionStrategy('v1'));
 
// Absolute path
echo $package->getUrl('/image.png');
// result: /image.png?v1
 
// Relative path
echo $package->getUrl('image.png');
// result: image.png?v1

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

// 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
 
echo $package->getUrl('image.png');
// result: v1/image.png

JSON File Manifest

A popular strategy to manage asset versioning, which is used by tools such asWebpack, is to generate a JSON file mapping all source file names to theircorresponding output file:

// rev-manifest.json
{
    "css/app.css": "build/css/app.b916426ea1d10021f3f17ce8031f93c2.css",
    "js/app.js": "build/js/app.13630905267b809161e71d0f8a0c017b.js",
    "...": "..."
}

In those cases, use theJsonManifestVersionStrategy:

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy;
 
$package = new Package(new JsonManifestVersionStrategy(__DIR__.'/rev-manifest.json'));
 
echo $package->getUrl('css/app.css');
// result: build/css/app.b916426ea1d10021f3f17ce8031f93c2.css

Custom Version Strategies

Use the VersionStrategyInterfaceto define your own versioning strategy. For example, your application may needto append the current date to all its web assets in order to bust the cacheevery day:

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). Ifthat's your case, replace the default Packageclass with PathPackage to avoid repeatingthat path over and over again:

use Symfony\Component\Asset\PathPackage;
// ...
 
$pathPackage = new PathPackage('/static/images', new StaticVersionStrategy('v1'));
 
echo $pathPackage->getUrl('logo.png');
// result: /static/images/logo.png?v1
 
// Base path is ignored when using absolute paths
echo $pathPackage->getUrl('/logo.png');
// result: /logo.png?v1

Request Context Aware Assets

If you are also using the HttpFoundationcomponent in your project (for instance, in a Symfony application), the PathPackageclass can take into account the context of the current request:

use Symfony\Component\Asset\Context\RequestStackContext;
use Symfony\Component\Asset\PathPackage;
// ...
 
$pathPackage = new PathPackage(
    '/static/images',
    new StaticVersionStrategy('v1'),
    new RequestStackContext($requestStack)
);
 
echo $pathPackage->getUrl('logo.png');
// result: /somewhere/static/images/logo.png?v1
 
// Both "base path" and "base url" are ignored when using absolute path for asset
echo $pathPackage->getUrl('/logo.png');
// result: /logo.png?v1

Now that the request context is set, the PathPackage will prepend thecurrent request base URL. So, for example, if your entire site is hosted underthe /somewhere directory of your web server root directory and the configuredbase path is /static/images, all paths will be prefixed with/somewhere/static/images.

Absolute Assets and CDNs

Applications that host their assets on different domains and CDNs (ContentDelivery Networks) should use the UrlPackageclass to generate absolute URLs for their assets:

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:

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 ifa visitor is viewing your site in https. If you want to use this, make surethat your CDN host supports HTTPS.

In case you serve assets from more than one domain to improve applicationperformance, pass an array of URLs as the first argument to the UrlPackageconstructor:

use Symfony\Component\Asset\UrlPackage;
// ...
 
$urls = [
    '//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 selectionis deterministic, meaning that each asset will always be served by the samedomain. This behavior simplifies the management of HTTP cache.

Request Context Aware Assets

Similarly to application-relative assets, absolute assets can also take intoaccount the context of the current request. In this case, only the requestscheme is considered, in order to select the appropriate base URL (HTTPs orprotocol-relative URLs for HTTPs requests, any base URL for HTTP requests):

use Symfony\Component\Asset\Context\RequestStackContext;
use Symfony\Component\Asset\UrlPackage;
// ...
 
$urlPackage = new UrlPackage(
    ['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 inpackages with the same versioning strategy and base path. The Asset componentincludes a Packages class to simplifymanagement of several packages.

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

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\Packages;
use Symfony\Component\Asset\PathPackage;
use Symfony\Component\Asset\UrlPackage;
// ...
 
$versionStrategy = new StaticVersionStrategy('v1');
 
$defaultPackage = new Package($versionStrategy);
 
$namedPackages = [
    '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 appliedto assets that don't define the name of package to use. In addition, thisapplication defines a package named img to serve images from an externaldomain and a doc package to avoid repeating long paths when linking to adocument inside a template:

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

Local Files and Other Protocols

In addition to HTTP this component supports other protocols (such as file://and ftp://). This allows for example to serve local files in order toimprove performance:

use Symfony\Component\Asset\UrlPackage;
// ...
 
$localPackage = new UrlPackage(
    'file:///path/to/images/',
    new EmptyVersionStrategy()
);
 
$ftpPackage = new UrlPackage(
    'ftp://example.com/images/',
    new EmptyVersionStrategy()
);
 
echo $localPackage->getUrl('/logo.png');
// result: file:///path/to/images/logo.png
 
echo $ftpPackage->getUrl('/logo.png');
// result: ftp://example.com/images/logo.png

Learn more

• How to manage CSS and JavaScript assets in Symfony applications
• WebLink component to preload assets using HTTP/2.