README

Assetic 是一个由 Winter CMS 团队维护的 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\UglifyCssFilter;

$css = new AssetCollection(array(
    new FileAsset('/path/to/src/styles.less', array(new LessFilter())),
    new GlobAsset('/path/to/css/*'),
), array(
    new UglifyCssFilter('/path/to/uglifycss'),
));

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

如果您遍历集合，则应用到集合的过滤器将级联到每个资产叶子上。

<?php

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

核心在 Assetic\Filter 命名空间中提供了以下过滤器

• CoffeeScriptFilter: 将 CoffeeScript 编译成 JavaScript
• CssImportFilter: 内联导入的样式表
• CSSMinFilter: 最小化 CSS
• CssRewriteFilter: 在移动到新 URL 时修复 CSS 资产中的相对 URL
• GoogleClosure\CompilerApiFilter: 使用 Google Closure Compiler API 编译 JavaScript
• HandlebarsFilter: 将 Handlebars 模板编译成 JavaScript
• JavaScriptMinifierFilter: 最小化 JavaScript
• JpegoptimFilter: 优化您的 JPEG 图像
• JpegtranFilter: 优化您的 JPEG 图像
• LessFilter: 使用 less.js 和 node.js 将 LESS 解析为 CSS
• LessphpFilter: 使用 lessphp 将 LESS 解析为 CSS
• OptiPngFilter: 优化您的 PNG 图像
• PackerFilter: 使用 Dean Edwards 的 Packer 压缩 JavaScript
• PhpCssEmbedFilter: 将图像数据嵌入到样式表中
• ReactJsxFilter: 将 React JSX 编译成 JavaScript
• ScssphpFilter: 将 SCSS 解析为 CSS
• SeparatorFilter: 在资产之间插入分隔符以防止合并失败
• StylesheetMinifyFilter: 压缩样式表 CSS 文件
• StylusFilter: 将 STYL 解析为 CSS
• TailwindCssFilter: 使用 Tailwind CSS 独立 CLI 工具构建 Tailwind CSS 样式表
• TypeScriptFilter: 将 TypeScript 解析为 JavaScript
• UglifyCssFilter: 最小化 CSS
• UglifyJs2Filter: 最小化 JavaScript
• UglifyJs3Filter: 最小化 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\ScssFilter;
use Assetic\Filter\CssMinFilter;

$fm = new FilterManager();
$fm->set('sass', new ScssFilter('/path/to/parser/scss'));
$fm->set('cssmin', new CssMinFilter());

资产工厂

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

<?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
    '?cssmin',        // don't use this filter in debug mode
));

echo $css->dump();

AssetFactory 使用根目录构造，该目录用作相对资产路径的基础目录。

在此处，将过滤器名称以问号开头，如 cssmin，将在工厂处于调试模式时省略该过滤器。

您还可以在工厂上注册 Workers，工厂创建的所有资产在返回之前都将传递给工作者的 process() 方法。有关示例，请参阅下面的 缓存失效。

将资产导出到静态文件

您可以将 AssetManager 持有的所有资产导出到目录中的文件。这可能在您的 web 服务器文档根目录下，以便可以静态地提供文件。

<?php

use Assetic\AssetWriter;

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

这将使用资产的目标路径。

缓存破坏

如果您像上面描述的那样从静态文件提供资产，您可以使用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\JavaScriptMinifierFilter;

$jsMinifier = new JavaScriptMinifierFilter();
$js = new AssetCache(
    new FileAsset('/path/to/some.js', array($jsMinifier)),
    new FilesystemCache('/path/to/cache')
);

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

Twig

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

<?php

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

一旦设置好，该扩展会公开一个类似资产工厂使用的语法风格的样式表和javascripts标签

{% 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 glob 引用的一个资产。除非使用 ? 前缀标记为可选，否则仍会应用指定的过滤器。

也可以通过在标签上设置 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 上找到）。