kekrozsak/vendor/kriswallsmith/assetic/docs/en/concepts.md

In order to use the Assetic OOP API you must first understand the two central
concepts of Assetic: assets and filters.

### What is an Asset?

As asset is an object that has content and metadata which can be loaded and
dumped. Your assets will probably fall into three categories: Javascripts,
stylesheets and images. Most assets will be loaded from files in your
filesystem, but they can also be loaded via HTTP, a database, from a string,
or virtually anything else. All that an asset has to do is fulfill Assetic's
basic asset interface.

### What is a Filter?

A filter is an object that acts upon an asset's content when that asset is
loaded and/or dumped. Similar to assets, a filter can do virtually anything,
as long as it implements Assetic's filter interface. 

Here is a list of some of the tools that can be applied to assets using a
filter:

 * CoffeeScript
 * CssEmbed
 * CssMin
 * Google Closure Compiler
 * jpegoptim
 * jpegtran
 * Less
 * LessPHP
 * optipng
 * Packager
 * pngout
 * SASS
 * Sprockets (version 1)
 * Stylus
 * YUI Compressor

### Using Assets and Filters

You need to start by creating an asset object. This will probably mean
instantiating a `FileAsset` instance, which takes a filesystem path as its
first argument:

    $asset = new Assetic\Asset\FileAsset('/path/to/main.css');

Once you have an asset you can begin adding filters to it by calling
`ensureFilter()`. For example, you can add a filter that applies the YUI
Compressor to the contents of the asset:

    $yui = new Assetic\Filter\Yui\CssCompressorFilter('/path/to/yui.jar');
    $asset->ensureFilter($yui);

Once you've added as many filters as you'd like you can output the finished
asset to the browser:

    header('Content-Type: text/css');
    echo $asset->dump();

### Asset Collections

It is a good idea to combine assets of the same type into a single file to
avoid unnecessary HTTP requests. You can do this in Assetic using the
`AssetCollection` class. This class is just like any other asset in Assetic's
eyes as it implements the asset interface, but under the hood it allows you to
combine multiple assets into one.

    use Assetic\Asset\AssetCollection;

    $asset = new AssetCollection(array(
        new FileAsset('/path/to/js/jquery.js'),
        new FileAsset('/path/to/js/jquery.plugin.js'),
        new FileAsset('/path/to/js/application.js'),
    ));

### Nested Asset Collections

The collection class implements the asset interface and all assets passed into
a collection must implement the same interface, which means you can easily
nest collections within one another:

    use Assetic\Asset\AssetCollection;
    use Assetic\Asset\GlobAsset;
    use Assetic\Asset\HttpAsset;

    $asset = new AssetCollection(array(
        new HttpAsset('http://example.com/jquery.min.js'),
        new GlobAsset('/path/to/js/*'),
    ));

The `HttpAsset` class is a special asset class that loads a file over HTTP;
`GlobAsset` is a special asset collection class that loads files based on a
filesystem glob -- both implement the asset interface.

This concept of nesting asset collection become even more powerful when you
start applying different sets of filters to each collection. Imagine some of
your application's stylesheets are written in SASS, while some are written in
vanilla CSS. You can combine all of these into one seamless CSS asset:

    use Assetic\Asset\AssetCollection;
    use Assetic\Asset\GlobAsset;
    use Assetic\Filter\SassFilter;
    use Assetic\Filter\Yui\CssCompressorFilter;

    $css = new AssetCollection(array(
        new GlobAsset('/path/to/sass/*.sass', array(new SassFilter())),
        new GlobAsset('/path/to/css/*.css'),
    ), array(
        new YuiCompressorFilter('/path/to/yuicompressor.jar'),
    ));

You'll notice I've also applied the YUI compressor filter to the combined
asset so all CSS will be minified.

### Iterating over an Asset Collection

Once you have an asset collection you can iterate over it like you would a
plain old PHP array:

    echo "Source paths:\n";
    foreach ($collection as $asset) {
        echo ' - '.$asset->getSourcePath()."\n";
    }

The asset collection iterates recursively, which means you will only see the
"leaf" assets during iteration. Iteration also includes a smart filter which
ensures you only see each asset once, even if the same asset has been included
multiple times.

Next: [Defining Assets "On The Fly"](define.md)