README

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

// the code is merged when the asset is dumped
echo $js->dump();

资产

Assetic 的资产是具有可过滤内容并可加载和卸载的东西。资产还包括元数据，其中一些可以被操作，而一些是不可变的。

过滤器

可以应用过滤器来操作资产。

<?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 编写框架
• CssEmbedFilter：在样式表中嵌入图像数据
• CssImportFilter：内联导入的样式表
• CssMinFilter：压缩 CSS
• CssRewriteFilter：修复 CSS 资产中的相对 URL，以便迁移到新的 URL
• DartFilter：使用 dart2js 编译 JavaScript
• EmberPrecompileFilter：预编译 Handlebars 模板为 JavaScript 以在 Ember.js 框架中使用
• GoogleClosure\CompilerApiFilter：使用 Google Closure Compiler API 编译 JavaScript
• GoogleClosure\CompilerJarFilter：使用 Google Closure Compiler JAR 编译 JavaScript
• GssFilter：使用 Google Closure Stylesheets Compiler 编译 CSS
• HandlebarsFilter：将 Handlebars 模板编译成 JavaScript
• JpegoptimFilter：优化您的 JPEG
• JpegtranFilter：优化您的 JPEG
• JSMinFilter：压缩 JavaScript
• JSMinPlusFilter：压缩 JavaScript
• LessFilter：将 LESS 解析为 CSS（使用 less.js 和 node.js）
• LessphpFilter：将 LESS 解析为 CSS（使用 lessphp）
• OptiPngFilter：优化您的 PNG
• PackagerFilter：解析 JavaScript 中的打包标签
• PackerFilter：使用 Dean Edwards 的 Packer 压缩 JavaScript
• PhpCssEmbedFilter：在样式表中嵌入图像数据
• PngoutFilter：优化您的 PNG
• Sass\SassFilter：将 SASS 解析为 CSS
• Sass\ScssFilter：将 SCSS 解析为 CSS
• ScssphpFilter：使用 scssphp 解析 SCSS
• SprocketsFilter：Sprockets JavaScript 依赖项管理
• StylusFilter：将 STYL 解析为 CSS
• TypeScriptFilter：将 TypeScript 解析为 JavaScript
• UglifyCssFilter：压缩 CSS
• UglifyJs2Filter：压缩 JavaScript
• UglifyJsFilter：压缩 JavaScript
• Yui\CssCompressorFilter：使用 YUI 压缩器压缩 CSS
• Yui\JsCompressorFilter：使用 YUI 压缩器压缩 JavaScript

资产管理器

资产管理器提供用于组织资产的工具。

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

过滤器管理器

还提供了过滤器管理器用于组织过滤器。

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

资产工厂

如果您不想手动创建所有这些对象，可以使用资产工厂，它会为您完成大部分工作。

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

在过滤器名称前加上问号，如这里的 yui_css，将在工厂处于调试模式时省略该过滤器。

缓存

提供了一个简单的缓存机制以避免不必要的操作。

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

缓存失效

您可以使用 CacheBustingWorker 来提供唯一的名称。

提供了两种策略：CacheBustingWorker::STRATEGY_CONTENT（基于内容），CacheBustingWorker::STRATEGY_MODIFICATION（基于修改时间）

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

静态资产

或者，您也可以直接将过滤后的资产写入您的网页目录，然后完成。

<?php

use Assetic\AssetWriter;

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

Twig

要使用Assetic的Twig扩展，您必须将其注册到Twig环境中

<?php

$twig->addExtension(new AsseticExtension($factory, $debug));

一旦设置好，该扩展将公开一个样式表和JavaScript标签，其语法与资产工厂使用的语法类似

{% 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);

Assetic基于Python的webassets库（可在GitHub上获取）。