Assetic is an asset management framework for PHP.
<?php
use Assetic\Asset\AssetCollection;
use Assetic\Asset\FileAsset;
use Assetic\Asset\GlobAsset;
$js = new AssetCollection(array(
new GlobAsset('/path/to/js/*'),
new FileAsset('/path/to/another.js'),
));
// the code is merged when the asset is dumped
echo $js->dump();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 can be applied to manipulate assets.
<?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.
<?php
foreach ($css as $leaf) {
// each leaf is compressed by YUI
echo $leaf->dump();
}The core provides the following filters in the Assetic\Filter namespace:
CoffeeScriptFilter: compiles CoffeeScript into JavascriptCssEmbedFilter: embeds image data in your stylesheetsCssImportFilter: inlines imported stylesheetsCssMinFilter: minifies CSSCssRewriteFilter: fixes relative URLs in CSS assets when moving to a new URLGoogleClosure\CompilerApiFilter: compiles Javascript using the Google Closure Compiler APIGoogleClosure\CompilerJarFilter: compiles Javascript using the Google Closure Compiler JARHandlebarsFilter: compiles Handlebars templates into JavascriptJpegoptimFilter: optimize your JPEGsJpegtranFilter: optimize your JPEGsLessFilter: parses LESS into CSS (using less.js with node.js)LessphpFilter: parses LESS into CSS (using lessphp)OptiPngFilter: optimize your PNGsPackerFilter: compresses Javascript using Dean Edwards's PackerPngoutFilter: optimize your PNGsCompassFilter: Compass CSS authoring frameworkSass\SassFilter: parses SASS into CSSSass\ScssFilter: parses SCSS into CSSSprocketsFilter: Sprockets Javascript dependency managementStylusFilter: parses STYL into CSSYui\CssCompressorFilter: compresses CSS using the YUI compressorYui\JsCompressorFilter: compresses Javascript using the YUI compressor
An asset manager is provided for organizing assets.
<?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.
<?php
use Assetic\Asset\AssetCollection;
use Assetic\Asset\AssetReference;
use Assetic\Asset\FileAsset;
$am->set('my_plugin', new AssetCollection(array(
new AssetReference($am, 'jquery'),
new FileAsset('/path/to/jquery.plugin.js'),
)));A filter manager is also provided for organizing filters.
<?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'));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.
<?php
use Assetic\Factory\AssetFactory;
$factory = new AssetFactory('/path/to/asset/directory/');
$factory->setAssetManager($am);
$factory->setFilterManager($fm);
$factory->setDebug(true);
$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
));
echo $css->dump();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.
A simple caching mechanism is provided to avoid unnecessary work.
<?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();You can use the CacheBustingWorker to provide unique names.
Two strategies are provided: CacheBustingWorker::STRATEGY_CONTENT (content based), CacheBustingWorker::STRATEGY_MODIFICATION (modification time based)
<?php
use Assetic\Factory\AssetFactory;
use Assetic\Factory\Worker\CacheBustingWorker;
$factory = new AssetFactory('/path/to/asset/directory/');
$factory->setAssetManager($am);
$factory->setFilterManager($fm);
$factory->setDebug(true);
$factory->addWorker(new CacheBustingWorker(CacheBustingWorker::STRATEGY_CONTENT));
$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
));
echo $css->dump();Alternatively you can just write filtered assets to your web directory and be done with it.
<?php
use Assetic\AssetWriter;
$writer = new AssetWriter('/path/to/web');
$writer->writeManagerAssets($am);To use the Assetic Twig extension you must register it to your Twig environment:
<?php
$twig->addExtension(new AsseticExtension($factory, $debug));Once in place, the extension exposes a stylesheets and a javascripts tag with a syntax similar to what the asset factory uses:
{% 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.
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.
This behavior can also be triggered by setting a debug attribute on the tag:
{% stylesheets 'css/*' debug=true %} ... {% stylesheets %}These assets need to be written to the web directory so these URLs don't return 404 errors.
<?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).