Skip to content

Assets Helper

Warning: You are browsing the documentation for Symfony 2.x, which is no longer maintained.

Consider upgrading your projects to Symfony 7.1.

The assets helper's main purpose is to make your application more portable by generating asset paths:

1
2
3
<link href="<?php echo $view['assets']->getUrl('css/style.css') ?>" rel="stylesheet">

<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>">

The assets helper can then be configured to render paths to a CDN or modify the paths in case your assets live in a sub-directory of your host (e.g. http://example.com/app).

Configure Paths

By default, the assets helper will prefix all paths with a slash. You can configure this by passing a base assets path as the first argument of the constructor:

1
2
3
4
use Symfony\Component\Templating\Helper\AssetsHelper;

// ...
$templateEngine->set(new AssetsHelper('/foo/bar'));

Now, if you use the helper, everything will be prefixed with /foo/bar:

1
2
3
4
<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>">
<!-- renders as:
<img src="/foo/bar/images/logo.png">
-->

Absolute Urls

You can also specify a URL to use in the second parameter of the constructor:

1
2
// ...
$templateEngine->set(new AssetsHelper(null, 'http://cdn.example.com/'));

Now URLs are rendered like http://cdn.example.com/images/logo.png.

You can also use the third argument of the helper to force an absolute URL:

1
2
3
4
<img src="<?php echo $view['assets']->getUrl('images/logo.png', null, true) ?>">
<!-- renders as:
<img src="http://yourwebsite.com/foo/bar/images/logo.png">
-->

Note

If you already set a URL in the constructor, using the third argument of getUrl() will not affect the generated URL.

Versioning

To avoid using the cached resource after updating the old resource, you can use versions which you bump every time you release a new project. The version can be specified in the third argument:

1
2
// ...
$templateEngine->set(new AssetsHelper(null, null, '328rad75'));

Now, every URL is suffixed with ?328rad75. If you want to have a different format, you can specify the new format in fourth argument. It's a string that is used in sprintf. The first argument is the path and the second is the version. For instance, %s?v=%s will be rendered as /images/logo.png?v=328rad75.

You can also generate a versioned URL on an asset-by-asset basis using the fourth argument of the helper:

1
2
3
4
<img src="<?php echo $view['assets']->getUrl('images/logo.png', null, false, '3.0') ?>">
<!-- renders as:
<img src="/images/logo.png?v=3.0">
-->

Multiple Packages

Asset path generation is handled internally by packages. The component provides 2 packages by default:

You can also use multiple packages:

1
2
3
4
5
6
7
use Symfony\Component\Templating\Asset\PathPackage;

// ...
$templateEngine->set(new AssetsHelper());

$templateEngine->get('assets')->addPackage('images', new PathPackage('/images/'));
$templateEngine->get('assets')->addPackage('scripts', new PathPackage('/scripts/'));

This will setup the assets helper with 3 packages: the default package which defaults to / (set by the constructor), the images package which prefixes it with /images/ and the scripts package which prefixes it with /scripts/.

If you want to set another default package, you can use setDefaultPackage().

You can specify which package you want to use in the second argument of getUrl():

1
2
3
4
<img src="<?php echo $view['assets']->getUrl('foo.png', 'images') ?>">
<!-- renders as:
<img src="/images/foo.png">
-->

Custom Packages

You can create your own package by extending Package.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version