Defining Assets "On The Fly"

----------------------------

The second approach to using Assetic involves defining your application's

assets "on the fly" in your templates, instead of in an isolated PHP file.

Using this approach, your PHP template would look something like this:

    <script src="<?php echo assetic_javascripts('js/*', 'yui_js') ?>"></script>

This call to `assetic_javascripts()` serves a dual purpose. It will be read by

the Assetic "formula loader" which will extract an asset "formula" that can be

used to build, dump and output the asset. It will also be executed when the

template is rendered, at which time the path to the output asset is output.

Assetic includes the following templating helper functions:

 * `assetic_image()`

 * `assetic_javascripts()`

 * `assetic_stylesheets()`

Defining assets on the fly is a much more sophisticated technique and

therefore relies on services to do the heavy lifting. The main one being the

asset factory.

### Asset Factory

The asset factory knows how to create asset objects using only arrays and

scalar values as input. This is the same string syntax used by the `assetic_*`

template helper functions.

    use Assetic\Factory\AssetFactory;

    $factory = new AssetFactory('/path/to/web');

    $js = $factory->createAsset(array(

        'js/jquery.js',

        'js/jquery.plugin.js',

        'js/application.js',

    ));

### Filter Manager

You can also apply filters to asset created by the factory. To do this you

must setup a `FilterManager`, which organizes filters by a name.

    use Assetic\FilterManager;

    use Assetic\Filter\GoogleClosure\ApiFilter as ClosureFilter;

    $fm = new FilterManager();

    $fm->set('closure', new ClosureFilter());

    $factory->setFilterManager($fm);

    $js = $factory->createAsset('js/*', 'closure');

This code creates an instance of the Google Closure Compiler filter and

assigns it the name `closure` using a filter manager. This filter manager is

then injected into the asset factory, making the filter available as `closure`

when creating assets.

### Debug Mode

The asset factory also introduces the concept of a debug mode. This mode

allows you to omit certain filters from assets the factory creates depending

on whether it is enabled or not.

For example, the YUI Compressor is awesome, but it is only appropriate in a

production environment as it is very difficult to debug minified Javascript.

    use Asset\Factory\AssetFactory;

    $factory = new AssetFactory('/path/to/web', true); // debug mode is on

    $factory->setFilterManager($fm);

    $js = $factory->createAsset('js/*', '?closure');

By prefixing the `closure` filter's name with a question mark, we are telling

the factory this filter is optional and should only be applied with debug mode

is off.

### Asset Manager and Asset References

The asset factory provides another special string syntax that allows you to

reference assets you defined elsewhere. These are called "asset references"

and involve an asset manager which, similar to the filter manager, organizes

assets by name.

    use Assetic\AssetManager;

    use Assetic\Asset\FileAsset;

    use Assetic\Factory\AssetFactory;

    $am = new AssetManager();

    $am->set('jquery', new FileAsset('/path/to/jquery.js'));

    $factory = new AssetFactory('/path/to/web');

    $factory->setAssetManager($am);

    $js = $factory->createAsset(array(

        '@jquery',

        'js/application.js',

    ));

### Extracting Assets from Templates

Once you've defined a set of assets in your templates you must use the

"formula loader" service to extract these asset definitions.

    use Assetic\Factory\Loader\FunctionCallsFormulaLoader;

    use Assetic\Factory\Resource\FileResource;

    $loader = new FunctionCallsFormulaLoader($factory);

    $formulae = $loader->load(new FileResource('/path/to/template.php'));

These asset formulae aren't much use by themselves. They each include just

enough information for the asset factory to create the intended asset object.

In order for these to be useful they must be wrapped in the special

`LazyAssetManager`.

### The Lazy Asset Manager

This service is a composition of the asset factory and one or more formula

loaders. It acts as the glue between these services behind the scenes, but can

be used just like a normal asset manager on the surface.

    use Assetic\Asset\FileAsset;

    use Assetic\Factory\LazyAssetManager;

    use Assetic\Factory\Loader\FunctionCallsFormulaLoader;

    use Assetic\Factory\Resource\DirectoryResource;

    $am = new LazyAssetManager($factory);

    $am->set('jquery', new FileAsset('/path/to/jquery.js'));

    $am->setLoader('php', new FunctionCallsFormulaLoader($factory));

    $am->addResource(new DirectoryResource('/path/to/templates', '/\.php$/'), 'php');

### Asset Writer

Finally, once you've create an asset manager that knows about every asset

you've defined in your templates, you must use an asset writer to actually

create the files your templates are going to be referencing.

    use Assetic\AssetWriter;

    $writer = new AssetWriter('/path/to/web');

    $writer->writeManagerAssets($am);

After running this script, all of the assets in your asset manager will be

loaded into memory, filtered with their configured filters and dumped to your

web directory as static files, ready to be served.