Access images in Symfony 2.1 CSS stylesheets with Twig and Assetic

Problem:

How can I access images from my Symfony 2.1 project's CSS stylesheets?

Solution -- intro:

The example in this blog post is only part of the picture and is meant to get the typical project started for the beginner. Please note that it's far from a complete explanation, but hopefully it'll be useful for some out there.

Accessing images in Symfony 2.1 stylesheets can be done by following a few steps. Before we list them out, let's establish some parameters for this blog post's example.

First, for illustration purposes, let's assume that your bundle is named DemoIllustrationBundle, its path is Demo/IllustrationBundle, and that your CSS and image files are located respectively in the following locations in src/Demo/IllustrationBundle/:

• Resources/public/css
• Resources/public/images

Let's also assume that our CSS file is named style.css, and that it needs to access the image 'repeat.png' to repeat as the background image.

In style.css, we'll access repeat.png via url('../images/repeat.png'), for example:

background-image: url('../images/repeat.png');

Now that we've established the parameters for this example, we can summarize the steps needed to be taken to properly access images in CSS styles:

• whitelist the bundle in assetic
• install web assets
• use stylesheets tag in twig template with cssrewrite filter
• compile assets for production (out of the scope of this blog post, but necessary to learn prior to switching to a production environment)

... whitelist bundle in assetic

This step allows you to use the stylesheets tag in your twig templates. You'll need this in order to use the rewrite filter to dynamically update the path of your images in the generated stylesheets of your app.

Open the file app/config.yml, it should have a section that looks like:

assetic:
  ...
  bundles:        []
  ...

Add your bundle to this whitelist. In the case of this blog post's example we'll add DemoIllustrationBundle:

bundles:        ['DemoIllustrationBundle']

Save this file and exit. Note that this assetic whitelist will now apply to all environments.

... install web assets

This step installs the images from your project's Resources/public folder to the web folder.

There are several ways to install assets. We'll be installing assets using the symlink method so we don't have to keep reinstalling them during development. In the command console / terminal, go to your project folder and use the command:

php app/console assets:install web --symlink

You should be able to access the CSS and image files in the web folder now. In the case of this example, they'd be located respectively in:

• web/bundles/demoillustration/css
• web/bundles/demoillustration/images

Note how these locations compare to your project's public folder.

... use the stylesheets tag with cssrewrite filter

When including the style.css file in this example, the twig template section should look like the following:

{% stylesheets 'bundles/demoillustration/css/style.css'
   filter="cssrewrite" %}
  <link href="{{ asset_url }}" rel="stylesheet" type="text/css" />
{% endstylesheets %}

This should rewrite the '../images/' in the stylesheet to the location of the installed images.

Debugging (incomplete):

There are a few things that can go wrong with the above example. This section will cover two of those bugs with potential approaches to debugging them.

Assetic not configured:

One error can be forgetting to whitelist your bundle. This is indicated by getting an exception such as the following:

An exception has been thrown during the compilation of a template ("You must add DemoIllustrationBundle to the assetic.bundle config to use the {% stylesheets %} tag in DemoIllustrationBundle::base.html.twig.") in "/path/to/Demo/IllustrationBundle/Resources/views/base.html.twig".

Images still aren't showing:

If the above steps were followed but images still aren't showing, there are a few things that should be looked at. We'll use the setup in the example of this blog post to illustrate a few steps that can be looked at when trying to debug this:

• are there any typos?
• are images located in the project's "Resources/public/images" folder?
• does the CSS file look for images in "../images/"?
• were web assets installed?

Unfortunately, since there is an exhaustive list of things that can potentially go wrong, you'll have to use your ingenuity or Google to search out any other scenarios besides the above ones if they don't seem to apply.

Further reading:

The example in this blog post is only part of the picture and is meant to get the typical project started for the beginner. There's a lot to learn, and several steps left to go in order to make your project suitable for production. The following links are either references that helped in figuring out the above steps in this post, in addition to other resources that may provide more useful information for either clarification or for how to proceed from where this post leaves off.

• http://stackoverflow.com/questions/9500573/path-of-assets-in-css-files-in-symfony2
• http://symfony.com/doc/current/book/templating.html
• http://stackoverflow.com/questions/10376946/assetic-unable-to-find-file
• http://tutorial.symblog.co.uk/docs/customising-the-view-more-with-twig.html
• http://symfony.com/doc/current/cookbook/assetic/asset_management.html