Including JavaScript Files

To include JavaScript files, use the javascripts tag in any template:

1
2
3

{% javascripts '@AcmeFooBundle/Resources/public/js/*' %}
    <script type="text/javascript" src="{{ asset_url }}"></script>
{% endjavascripts %}

1
2
3
4
5

<?php foreach ($view['assetic']->javascripts(
    array('@AcmeFooBundle/Resources/public/js/*')
) as $url): ?>
    <script type="text/javascript" src="<?php echo $view->escape($url) ?>"></script>
<?php endforeach; ?>

1
2
3
4
5
6
7

{# ... #}
{% block javascripts %}
    {% javascripts '@AcmeFooBundle/Resources/public/js/*' %}
        <script type="text/javascript" src="{{ asset_url }}"></script>
    {% endjavascripts %}
{% endblock %}
{# ... #}

In this example, all of the files in the Resources/public/js/ directory of the AcmeFooBundle will be loaded and served from a different location. The actual rendered tag might simply look like:

1

<script src="/app_dev.php/js/abcd123.js"></script>

This is a key point: once you let Assetic handle your assets, the files are served from a different location. This will cause problems with CSS files that reference images by their relative path. See How to Use Assetic for Asset Management.

Including CSS Stylesheets

To bring in CSS stylesheets, you can use the same methodologies seen above, except with the stylesheets tag:

1
2
3

{% stylesheets 'bundles/acme_foo/css/*' filter='cssrewrite' %}
    <link rel="stylesheet" href="{{ asset_url }}" />
{% endstylesheets %}

1
2
3
4
5
6

<?php foreach ($view['assetic']->stylesheets(
    array('bundles/acme_foo/css/*'),
    array('cssrewrite')
) as $url): ?>
    <link rel="stylesheet" href="<?php echo $view->escape($url) ?>" />
<?php endforeach; ?>

1
2
3
4
5
6
7

{# ... #}
{% block stylesheets %}
    {% stylesheets 'bundles/acme_foo/css/*' filter='cssrewrite' %}
        <link rel="stylesheet" href="{{ asset_url }}" />
    {% endstylesheets %}
{% endblock %}
{# ... #}

But because Assetic changes the paths to your assets, this will break any background images (or other paths) that uses relative paths, unless you use the cssrewrite filter.

Including Images

To include an image you can use the image tag.

1
2
3

{% image '@AcmeFooBundle/Resources/public/images/example.jpg' %}
    <img src="{{ asset_url }}" alt="Example" />
{% endimage %}

1
2
3
4
5

<?php foreach ($view['assetic']->image(
    array('@AcmeFooBundle/Resources/public/images/example.jpg')
) as $url): ?>
    <img src="<?php echo $view->escape($url) ?>" alt="Example" />
<?php endforeach; ?>

You can also use Assetic for image optimization. More information in How to Use Assetic for Image Optimization with Twig Functions.

Fixing CSS Paths with the cssrewrite Filter

Since Assetic generates new URLs for your assets, any relative paths inside your CSS files will break. To fix this, make sure to use the cssrewrite filter with your stylesheets tag. This parses your CSS files and corrects the paths internally to reflect the new location.

You can see an example in the previous section.

Combining Assets

One feature of Assetic is that it will combine many files into one. This helps to reduce the number of HTTP requests, which is great for front end performance. It also allows you to maintain the files more easily by splitting them into manageable parts. This can help with re-usability as you can easily split project-specific files from those which can be used in other applications, but still serve them as a single file:

1
2
3
4
5
6

{% javascripts
    '@AcmeFooBundle/Resources/public/js/*'
    '@AcmeBarBundle/Resources/public/js/form.js'
    '@AcmeBarBundle/Resources/public/js/calendar.js' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

1
2
3
4
5
6
7
8
9

<?php foreach ($view['assetic']->javascripts(
    array(
        '@AcmeFooBundle/Resources/public/js/*',
        '@AcmeBarBundle/Resources/public/js/form.js',
        '@AcmeBarBundle/Resources/public/js/calendar.js',
    )
) as $url): ?>
    <script src="<?php echo $view->escape($url) ?>"></script>
<?php endforeach; ?>

In the dev environment, each file is still served individually, so that you can debug problems more easily. However, in the prod environment (or more specifically, when the debug flag is false), this will be rendered as a single script tag, which contains the contents of all of the JavaScript files.

And combining files doesn't only apply to your files. You can also use Assetic to combine third party assets, such as jQuery, with your own into a single file:

1
2
3
4
5

{% javascripts
    '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js'
    '@AcmeFooBundle/Resources/public/js/*' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

1
2
3
4
5
6
7
8

<?php foreach ($view['assetic']->javascripts(
    array(
        '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js',
        '@AcmeFooBundle/Resources/public/js/*',
    )
) as $url): ?>
    <script src="<?php echo $view->escape($url) ?>"></script>
<?php endforeach; ?>

Using Named Assets

AsseticBundle configuration directives allow you to define named asset sets. You can do so by defining the input files, filters and output files in your configuration under the assetic section. Read more in the assetic config reference.

1
2
3
4
5
6
7

# app/config/config.yml
assetic:
    assets:
        jquery_and_ui:
            inputs:
                - '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js'
                - '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.ui.js'

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

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:assetic="http://symfony.com/schema/dic/assetic">

    <assetic:config>
        <assetic:asset name="jquery_and_ui">
            <assetic:input>@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js</assetic:input>
            <assetic:input>@AcmeFooBundle/Resources/public/js/thirdparty/jquery.ui.js</assetic:input>
        </assetic:asset>
    </assetic:config>
</container>

1
2
3
4
5
6
7
8
9
10
11

// app/config/config.php
$container->loadFromExtension('assetic', array(
    'assets' => array(
        'jquery_and_ui' => array(
            'inputs' => array(
                '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js',
                '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.ui.js',
            ),
        ),
    ),
);

After you have defined the named assets, you can reference them in your templates with the @named_asset notation:

1
2
3
4
5

{% javascripts
    '@jquery_and_ui'
    '@AcmeFooBundle/Resources/public/js/*' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

1
2
3
4
5
6
7
8

<?php foreach ($view['assetic']->javascripts(
    array(
        '@jquery_and_ui',
        '@AcmeFooBundle/Resources/public/js/*',
    )
) as $url): ?>
    <script src="<?php echo $view->escape($url) ?>"></script>
<?php endforeach; ?>

Dumping Asset Files in the prod Environment

In the prod environment, your JS and CSS files are represented by a single tag each. In other words, instead of seeing each JavaScript file you're including in your source, you'll likely just see something like this:

1

<script src="/js/abcd123.js"></script>

Moreover, that file does not actually exist, nor is it dynamically rendered by Symfony (as the asset files are in the dev environment). This is on purpose - letting Symfony generate these files dynamically in a production environment is just too slow.

Instead, each time you use your app in the prod environment (and therefore, each time you deploy), you should run the following task:

1

$ php app/console assetic:dump --env=prod --no-debug

This will physically generate and write each file that you need (e.g. /js/abcd123.js). If you update any of your assets, you'll need to run this again to regenerate the file.

Dumping Asset Files in the dev Environment

By default, each asset path generated in the dev environment is handled dynamically by Symfony. This has no disadvantage (you can see your changes immediately), except that assets can load noticeably slow. If you feel like your assets are loading too slowly, follow this guide.

First, tell Symfony to stop trying to process these files dynamically. Make the following change in your config_dev.yml file:

1
2
3

# app/config/config_dev.yml
assetic:
    use_controller: false

1
2

<!-- app/config/config_dev.xml -->
<assetic:config use-controller="false" />

1
2
3
4

// app/config/config_dev.php
$container->loadFromExtension('assetic', array(
    'use_controller' => false,
));

Next, since Symfony is no longer generating these assets for you, you'll need to dump them manually. To do so, run the following:

1

$ php app/console assetic:dump

This physically writes all of the asset files you need for your dev environment. The big disadvantage is that you need to run this each time you update an asset. Fortunately, by passing the --watch option, the command will automatically regenerate assets as they change:

1

$ php app/console assetic:dump --watch

Since running this command in the dev environment may generate a bunch of files, it's usually a good idea to point your generated assets files to some isolated directory (e.g. /js/compiled), to keep things organized:

1
2
3

{% javascripts '@AcmeFooBundle/Resources/public/js/*' output='js/compiled/main.js' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

1
2
3
4
5
6
7

<?php foreach ($view['assetic']->javascripts(
    array('@AcmeFooBundle/Resources/public/js/*'),
    array(),
    array('output' => 'js/compiled/main.js')
) as $url): ?>
    <script src="<?php echo $view->escape($url) ?>"></script>
<?php endforeach; ?>