supa86000/zf2-assetic

Asset Management for PHP

Assetic

Assetic is an asset management framework for PHP., _(*1)

``` php <?php, <sub>(*2)</sub>

use Assetic\Asset\AssetCollection; use Assetic\Asset\FileAsset; use Assetic\Asset\GlobAsset;, <sub>(*3)</sub>

$js = new AssetCollection(array( new GlobAsset('/path/to/js/*'), new FileAsset('/path/to/another.js'), ));, <sub>(*4)</sub>

// the code is merged when the asset is dumped echo $js->dump();, <sub>(*5)</sub>

Assets
------

An Assetic asset is something with filterable content that can be loaded and
dumped. An asset also includes metadata, some of which can be manipulated and
some of which is immutable.

| **Property** | **Accessor**    | **Mutator**   |
|--------------|-----------------|---------------|
| content      | getContent      | setContent    |
| mtime        | getLastModified | n/a           |
| source root  | getSourceRoot   | n/a           |
| source path  | getSourcePath   | n/a           |
| target path  | getTargetPath   | setTargetPath |

Filters
-------

Filters can be applied to manipulate assets.

``` php
<?php

use Assetic\Asset\AssetCollection;
use Assetic\Asset\FileAsset;
use Assetic\Asset\GlobAsset;
use Assetic\Filter\LessFilter;
use Assetic\Filter\Yui;

$css = new AssetCollection(array(
    new FileAsset('/path/to/src/styles.less', array(new LessFilter())),
    new GlobAsset('/path/to/css/*'),
), array(
    new Yui\CssCompressorFilter('/path/to/yuicompressor.jar'),
));

// this will echo CSS compiled by LESS and compressed by YUI
echo $css->dump();

The filters applied to the collection will cascade to each asset leaf if you iterate over it., <sub>(*6)</sub>

``` php <?php, <sub>(*7)</sub>

foreach ($css as $leaf) { // each leaf is compressed by YUI echo $leaf->dump(); }, <sub>(*8)</sub>

The core provides the following filters in the `Assetic\Filter` namespace:

 * `CoffeeScriptFilter`: compiles CoffeeScript into Javascript
 * `CompassFilter`: Compass CSS authoring framework
 * `CssEmbedFilter`: embeds image data in your stylesheets
 * `CssImportFilter`: inlines imported stylesheets
 * `CssMinFilter`: minifies CSS
 * `CssRewriteFilter`: fixes relative URLs in CSS assets when moving to a new URL
 * `DartFilter`: compiles Javascript using dart2js
 * `EmberPrecompileFilter`: precompiles Handlebars templates into Javascript for use in the Ember.js framework
 * `GoogleClosure\CompilerApiFilter`: compiles Javascript using the Google Closure Compiler API
 * `GoogleClosure\CompilerJarFilter`: compiles Javascript using the Google Closure Compiler JAR
 * `GssFilter`: compliles CSS using the Google Closure Stylesheets Compiler
 * `HandlebarsFilter`: compiles Handlebars templates into Javascript
 * `JpegoptimFilter`: optimize your JPEGs
 * `JpegtranFilter`: optimize your JPEGs
 * `JSMinFilter`: minifies Javascript
 * `JSMinPlusFilter`: minifies Javascript
 * `LessFilter`: parses LESS into CSS (using less.js with node.js)
 * `LessphpFilter`: parses LESS into CSS (using lessphp)
 * `OptiPngFilter`: optimize your PNGs
 * `PackagerFilter`: parses Javascript for packager tags
 * `PackerFilter`: compresses Javascript using Dean Edwards's Packer
 * `PhpCssEmbedFilter`: embeds image data in your stylesheet
 * `PngoutFilter`: optimize your PNGs
 * `Sass\SassFilter`: parses SASS into CSS
 * `Sass\ScssFilter`: parses SCSS into CSS
 * `ScssphpFilter`: parses SCSS using scssphp
 * `SprocketsFilter`: Sprockets Javascript dependency management
 * `StylusFilter`: parses STYL into CSS
 * `TypeScriptFilter`: parses TypeScript into Javascript
 * `UglifyCssFilter`: minifies CSS
 * `UglifyJs2Filter`: minifies Javascript
 * `UglifyJsFilter`: minifies Javascript
 * `Yui\CssCompressorFilter`: compresses CSS using the YUI compressor
 * `Yui\JsCompressorFilter`: compresses Javascript using the YUI compressor

Asset Manager
-------------

An asset manager is provided for organizing assets.

``` php
<?php

use Assetic\AssetManager;
use Assetic\Asset\FileAsset;
use Assetic\Asset\GlobAsset;

$am = new AssetManager();
$am->set('jquery', new FileAsset('/path/to/jquery.js'));
$am->set('base_css', new GlobAsset('/path/to/css/*'));

The asset manager can also be used to reference assets to avoid duplication., <sub>(*9)</sub>

``` php <?php, <sub>(*10)</sub>

use Assetic\Asset\AssetCollection; use Assetic\Asset\AssetReference; use Assetic\Asset\FileAsset;, <sub>(*11)</sub>

$am->set('my_plugin', new AssetCollection(array( new AssetReference($am, 'jquery'), new FileAsset('/path/to/jquery.plugin.js'), )));, <sub>(*12)</sub>

Filter Manager
--------------

A filter manager is also provided for organizing filters.

``` php
<?php

use Assetic\FilterManager;
use Assetic\Filter\Sass\SassFilter;
use Assetic\Filter\Yui;

$fm = new FilterManager();
$fm->set('sass', new SassFilter('/path/to/parser/sass'));
$fm->set('yui_css', new Yui\CssCompressorFilter('/path/to/yuicompressor.jar'));

Asset Factory

If you'd rather not create all these objects by hand, you can use the asset factory, which will do most of the work for you., <sub>(*13)</sub>

``` php <?php, <sub>(*14)</sub>

use Assetic\Factory\AssetFactory;, <sub>(*15)</sub>

$factory = new AssetFactory('/path/to/asset/directory/'); $factory->setAssetManager($am); $factory->setFilterManager($fm); $factory->setDebug(true);, <sub>(*16)</sub>

$css = $factory->createAsset(array( '@reset', // load the asset manager's "reset" asset 'css/src/*.scss', // load every scss files from "/path/to/asset/directory/css/src/" ), array( 'scss', // filter through the filter manager's "scss" filter '?yui_css', // don't use this filter in debug mode ));, <sub>(*17)</sub>

echo $css->dump();, <sub>(*18)</sub>

Prefixing a filter name with a question mark, as `yui_css` is here, will cause
that filter to be omitted when the factory is in debug mode.

Caching
-------

A simple caching mechanism is provided to avoid unnecessary work.

``` php
<?php

use Assetic\Asset\AssetCache;
use Assetic\Asset\FileAsset;
use Assetic\Cache\FilesystemCache;
use Assetic\Filter\Yui;

$yui = new Yui\JsCompressorFilter('/path/to/yuicompressor.jar');
$js = new AssetCache(
    new FileAsset('/path/to/some.js', array($yui)),
    new FilesystemCache('/path/to/cache')
);

// the YUI compressor will only run on the first call
$js->dump();
$js->dump();
$js->dump();

Cache Busting

You can use the CacheBustingWorker to provide unique names., <sub>(*19)</sub>

Two strategies are provided: CacheBustingWorker::STRATEGY_CONTENT (content based), CacheBustingWorker::STRATEGY_MODIFICATION (modification time based), <sub>(*20)</sub>

``` php <?php, <sub>(*21)</sub>

use Assetic\Factory\AssetFactory; use Assetic\Factory\Worker\CacheBustingWorker;, <sub>(*22)</sub>

$factory = new AssetFactory('/path/to/asset/directory/'); $factory->setAssetManager($am); $factory->setFilterManager($fm); $factory->setDebug(true); $factory->addWorker(new CacheBustingWorker(CacheBustingWorker::STRATEGY_CONTENT));, <sub>(*23)</sub>

$css = $factory->createAsset(array( '@reset', // load the asset manager's "reset" asset 'css/src/*.scss', // load every scss files from "/path/to/asset/directory/css/src/" ), array( 'scss', // filter through the filter manager's "scss" filter '?yui_css', // don't use this filter in debug mode ));, <sub>(*24)</sub>

echo $css->dump();, <sub>(*25)</sub>

Static Assets
-------------

Alternatively you can just write filtered assets to your web directory and be
done with it.

``` php
<?php

use Assetic\AssetWriter;

$writer = new AssetWriter('/path/to/web');
$writer->writeManagerAssets($am);

Twig

To use the Assetic [Twig][3] extension you must register it to your Twig environment:, <sub>(*26)</sub>

``` php <?php, <sub>(*27)</sub>

$twig->addExtension(new AsseticExtension($factory, $debug));, <sub>(*28)</sub>

Once in place, the extension exposes a stylesheets and a javascripts tag with a syntax similar
to what the asset factory uses:

``` html+jinja
{% stylesheets '/path/to/sass/main.sass' filter='sass,?yui_css' output='css/all.css' %}
    <link href="{{ asset_url }}" type="text/css" rel="stylesheet" />
{% endstylesheets %}

This example will render one link element on the page that includes a URL where the filtered asset can be found., <sub>(*29)</sub>

When the extension is in debug mode, this same tag will render multiple link elements, one for each asset referenced by the css/src/*.sass glob. The specified filters will still be applied, unless they are marked as optional using the ? prefix., <sub>(*30)</sub>

This behavior can also be triggered by setting a debug attribute on the tag:, <sub>(*31)</sub>

``` html+jinja {% stylesheets 'css/*' debug=true %} ... {% stylesheets %}, <sub>(*32)</sub>

These assets need to be written to the web directory so these URLs don't
return 404 errors.

``` php
<?php

use Assetic\AssetWriter;
use Assetic\Extension\Twig\TwigFormulaLoader;
use Assetic\Extension\Twig\TwigResource;
use Assetic\Factory\LazyAssetManager;

$am = new LazyAssetManager($factory);

// enable loading assets from twig templates
$am->setLoader('twig', new TwigFormulaLoader($twig));

// loop through all your templates
foreach ($templates as $template) {
    $resource = new TwigResource($twigLoader, $template);
    $am->addResource($resource, 'twig');
}

$writer = new AssetWriter('/path/to/web');
$writer->writeManagerAssets($am);

Assetic is based on the Python webassets library (available on GitHub)., <sub>(*33)</sub>