Введение в фреймворк Kriswallsmith Assetic

Пожалуй, одной из самых мощных библиотек для управления статическими файлами (стилями, джава-скриптами, изображениями) через PHP-скрипты является Assetic. Тем не менее, начать с ходу использовать Assetic под силу далеко не каждому профессионалу. Не говоря уже о новичках, для которых серьезным барьером является и английский язык.

Библиотека решает такие задачи, как:

• Публикация статических фалов, находящихся в модулях за пределами директории веб-сервера
• Объединение мелких файлов скриптов или стилей в один для ускорения загрузки
• Встраивание мелких изображений в файлы стилей в кодировке base64 для ускорения загрузки
• Обработка и компиляция стилей и скриптов из различных языков, таких как less или coffeescript в нативные css и javascript
• Сжатие стилей и скриптов средствами различных оптимайзеров по вкусу
• Оптимизация изображений PNG и Jpeg без потери качества

Данный перевод из официальной документации является введением в Kriswallsmith Assetic

Assetic

Assetic - это фреймворк для управления статическими активами для 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'),
));

// код объединяет файлы при выгрузке
echo $js->dump();

Assets

Для Assetic активами является что-то с фильтруемым контентом, который можно сначала загрузить, а потом выгрузить. Актив так же включает в себя метаданные, некоторыми из них них можно управлять, а некоторые неизменны:

The "target path" property denotes where an asset (or an collection of assets) should be dumped. Свойство "target path" указывает, куда актив (или коллекция активов) должен быть выгружен.

Filters

Фильтры могут применяться для управления активами.

<?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();

Фильтры, примененные к коллекции будут каскадно применены к каждому активу-листу, если вы будете перебирать её.

<?php

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

Ядро представляет следующие фильтры в пространстве имен Assetic\Filter:

• CoffeeScriptFilter: компиляция CoffeeScript в Javascript
• CompassFilter: Compass CSS authoring framework
• CssEmbedFilter: встраивает изображения в таблицы стилей в виде base64
• CssImportFilter: inlines imported stylesheets
• CssMinFilter: минификация CSS
• CssRewriteFilter: исправляет относительные URLы в CSS-активах, когда они перемещаются на другой URL
• DartFilter: компилирует Javascript использую dart2js
• EmberPrecompileFilter: прекомпилирует Handlebars шаблоны в Javascript для использования их в фреймворке Ember.js
• GoogleClosure\CompilerApiFilter: компилирует Javascript используя Google Closure Compiler API
• GoogleClosure\CompilerJarFilter: компилирует Javascript используя Google Closure Compiler JAR
• GssFilter: компилирует CSS используя Google Closure Stylesheets Compiler
• HandlebarsFilter: компилирует Handlebars шаблоны в Javascript
• JpegoptimFilter: оптимизирует ваши JPEGs
• JpegtranFilter: оптимизирует ваши JPEGs
• JSMinFilter: минимизирует Javascript
• JSMinPlusFilter: минимизирует Javascript
• JSqueezeFilter: сжимает Javascript
• LessFilter: парсит LESS в CSS (используя less.js с node.js)
• LessphpFilter: парсит LESS в CSS (использую lessphp)
• OptiPngFilter: оптимизирует ваши PNGs
• PackagerFilter: парсит Javascript для упаковщика тегов
• PackerFilter: сжимает Javascript использую Dean Edwards's Packer
• PhpCssEmbedFilter: встраивает изображения в ваши таблицы стилей как base64
• PngoutFilter: оптимизирует ваши PNGs
• Sass\SassFilter: parses SASS into CSS
• Sass\ScssFilter: parses SCSS into CSS
• ScssphpFilter: parses SCSS using scssphp
• SprocketsFilter: Sprockets Javascript управление зависимостями
• StylusFilter: парсит STYL в CSS
• TypeScriptFilter: парсит TypeScript в Javascript
• UglifyCssFilter: минимизирует CSS
• UglifyJs2Filter: минимизирует Javascript
• UglifyJsFilter: минимизирует Javascript
• Yui\CssCompressorFilter: сжимает CSS используя YUI compressor
• Yui\JsCompressorFilter: сжимает Javascript используя YUI compressor

Asset Manager

Менеджер активов обеспечивает управление активами.

<?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/*'));

Менеджер активов может также использоваться для ссылки на активы, чтобы избежать дублирования.

<?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'),
)));

Filter Manager

Менеджер фильтров также предоставляет управление фильтрами.

<?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

Если не хочется создавать все эти объекты вручную, можно использовать фабрику активов, которая будет делать большую часть работы.

<?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();

При создании AssetFactory ей передается корневая директория, которая используется как базовая директория для относительных путей активов.

Если поставить перед именем фильтра вопросительный знак, как ?yui_css в примере, то такой фильтр не будет применен, если фабрика находится в режиме отладки.

Для фабрики также можно зарегистрировать Рабочих, и тогда все активы, созданные ей будут проходить через метод рабочего process() перед тем, как фабрика вернет их. См. Cache Busting в примере ниже.

Выгрузка Активов в статические файлы

Все активы, которыми управляет AssetManager можно выгрузить, как файлы в директорию. Вероятно, это нужно делать под корневой директорией веб-сервера, чтобы выгруженные файлы могли быть загружены браузером.

<?php

use Assetic\AssetWriter;

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

Это будет сделано в target path актива.

Cache Busting

Если активы обрабатываются из статических файлов, как описано выше, то можно использовать рабочего CacheBustingWorker чтобы переписать (изменить) целевые пути для активов. Он будет вставлять уникальный идентификатор перед расширением в имени файла, для конкретной версии актива.

Идентификатор основан на времени модификации актива, но будет также зависеть от фильтров активов, которые его поддерживают.

<?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());

$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();

Внутреннее кеширование

Предоставляется простой механизм кеширования, чтобы избежать лишней работы.

<?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();

Twig

Чтобы использовать Assetic как расширение Twig, нужно зарегистрировать его в Twig-окружении.

<?php
$twig->addExtension(new AsseticExtension($factory));

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 %}

Этот пример отобразит один элемент link на странице, который будет включать URL, где может быть найден отфильтрованный актив.

Когда расширение в режиме отладки, этот же тег будет выводить несколько элементов link, по одному для каждого актива, которые ссылаются на css/src/*.sass. Указанные фильтры будут по прежнему применяться, пока они не будут отмечены как опциональные, используя знак ? префикс.

Это поведение так же может срабатывать, если на теге установлен атрибутdebug.

{% stylesheets 'css/*' debug=true %} ... {% stylesheets %}

Эти активы должны быть записаны в веб-директории, так что URLы не вернут ошибок 404.

<?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);

UPD: Статья содержит вольный перевод документации и находится здесь в исключительно ознакомительных целях для энтузиастов. Автор блога осознал, что лучше всего для управления скриптаим и стилями подходят инструменты на nodejs, например, использование Grunt.