corneltek/assetkit

高性能资产管理器。

维护者

详细信息

github.com/c9s/AssetKit

源代码

问题

安装数: 1,402

依赖项: 11

建议者: 0

安全性: 0

星级: 54

关注者: 7

分支: 5

开放问题: 8

语言:HTML

3.4.4 2016-10-10 08:56 UTC

Requires

Requires (Dev)

MIT 61210e17af53cbb82d5fd5fca007071198fe30a1

  • c9s <yoanlin93+composer.woop@gmail.com>

javascriptassetmanagercompresscssminsquash

This package is auto-updated.

Last update: 2024-09-14 15:21:56 UTC

README

AssetKit旨在优化PHP性能，所有配置文件都编译成PHP源代码，这使得AssetKit能够快速加载这些资产配置文件。

AssetKit是一个强大的资产管理器，提供了一个简单的命令行界面和简单的PHP库，API简单，内置了许多内置的过滤器和解压器。

Build Status Coverage Status

概念

  • 为了提高资产加载性能，我们将这些所需的资产清单文件注册到AssetKit配置文件中，其中包含资产源目录和其他清单文件信息。配置文件被转换为PHP源代码。

  • 当从网页中请求一个资产时，可以通过AssetLoader快速加载该资产，然后资产将经过过滤器过滤，并编译/压缩为前端输出。如果是在生产环境中，AssetRenderer会为您缓存URL清单，因此您不必每次都编译这些资产。

  • 在生产模式下，资产编译器将加载的资产文件压缩为最小化文件。

  • 在开发模式下，资产编译器简单地渲染包含路径。

  • 您可以在每个不同的页面中定义不同的必需资产，每个页面都有一个页面ID（目标）。

    页面ID（目标）也用于缓存结果。

    因此，在您的产品页面中，您可以包含与页面ID "yourapp-products" 一起的 jquery 和 product 资产。在您的主页中，您可以包含与页面ID "youapp-mainpage" 一起的 jquery 和 mainpage 资产。

  • 一个资产可以拥有多个文件集合，文件集合可以是CSS、SCSS、SASS、CoffeeScript、LiveScript或JavaScript集合。

  • 每个文件集合都可以有自己的过滤器和解压器。例如，CSS文件集合可以使用 "cssmin" 和 "yuicss" 解压器，而SASS文件集合可以使用 "sass" 过滤器和 "cssmin" 解压器来生成最小化输出。

  • "目标"由多个资产组成，类似于 "页面"，我们通常在一个单独的页面中包含多个资产，称为 "目标"。

为什么我们要单独加载不同的资产并定义资产清单？因为在现代Web应用程序中，大多数组件都是模块化的，所以在一个应用程序中，有许多不同的插件、模块、库。一些插件可能提供自己的资产，但一些没有。一些资产需要通过特定的过滤器进行编译，但一些不需要。一些资产需要通过像 'CSSMin' 或 'JSMin' 这样的解压器进行压缩，但一些不需要。

在开发前端文件时，我们通常需要反复重新编译这些资产文件，最后，我们仍然需要将它们重新编译成一个单一的压缩文件以提高前端性能。为了重新编译这些文件，一些人使用Makefile，一些人使用Grunt.js，但这仍然很难配置、管理和分发。

为了给PHP应用程序提供更好的灵活性，我们设计了一个更好的架构来组织这些资产文件。这就是AssetKit。

功能

  • 集中式资产配置。
  • 自动获取和更新您的资产文件。
  • AssetCompiler：将多个资产编译成一个压缩文件。
  • AssetRender：将编译后的资产渲染为HTML片段、样式表标签或脚本标签。
  • 命令行工具，用于安装、注册和预编译资源。
  • CSSMin压缩器、YUI压缩器、JSMin压缩器、CoffeeScript、SASS、SCSS过滤器。
  • APC缓存支持，缓存编译后的清单，因此您无需每次都重新编译。
  • Twig扩展支持。（见下文）

需求

  • yaml扩展。

安装

安装需求

$ gem install compass sass   # for sass/compass filter
$ npm install coffee-script  # for coffee-script filter

从composer安装库

{
    "require": {
        "corneltek/assetkit": "~3"
    }
}

获取命令行assetkit

$ curl -O https://raw.github.com/c9s/AssetKit/master/assetkit
$ chmod +x assetkit
$ sudo mv assetkit /usr/bin

演示

git clone https://github.com/c9s/AssetKit
cd demo
php -S localhost:3000
// open your browser and go to http://localhost:3000 to see the sample app in production mode.

// http://localhost:3000/index.php?force=1 to force the asset compilation

资产清单文件

要定义文件集合，您需要在资产目录中创建一个manifest.yml文件，例如，backbonejs的manifest.yml文件

---
resource:
  url: https://backbone.npmjs.net.cn/backbone.js
collections:
  - js:
    - backbone.js
  - css:
    - app.css
  - sass:
    - home.sass

您也可以定义资源，assetkit会为您获取。目前assetkit支持svn、git、hg资源类型。

基本用法

一旦您获得assetkit，您可以使用您的公共路径（网站根目录）初始化它

$ assetkit init --baseDir "public/assets" --baseUrl "/assets" assetkit.yml

配置存储在assetkit.yml文件中。

然后获取您想要的任何东西

$ assetkit add assets/jquery
Submodule 'src/sizzle' () registered for path 'src/sizzle'
Submodule 'test/qunit' () registered for path 'test/qunit'
Submodule 'src/sizzle' () registered for path 'src/sizzle'
Submodule 'test/qunit' () registered for path 'test/qunit'
Checking jQuery against JSHint...
JSHint check passed.
jQuery Size - compared to last make
  252787      (-) jquery.js
   94771      (-) jquery.min.js
   33635      (-) jquery.min.js.gz
jQuery build complete.
Saving config...
Done

并且您的assetkit.yml文件将更新，这些资产文件将安装到public/assets。

注意：要使用符号链接安装资产文件，请使用--link选项，这对于资产开发来说很方便。

如果有人想克隆您的项目，您可以将assetkit.yml文件添加到仓库中，然后B可以执行update命令来更新资产。

$ assetkit update

要在您的应用程序中使用assetkit，只需几行代码即可

// load the autoload.php from composer
require 'vendor/autoload.php';

// load your asset config file, this contains asset manifest and types
$config = new AssetKit\AssetConfig( '../assetkit.yml', array( 
    'root' => APP_ROOT // the absolute path where you run "assetkit" command.
));

// initialize an asset loader
$loader = new AssetKit\AssetLoader( $config );

// load the required assets (of your page, application or controller)
$assets = $loader->loadAssets(array( 'jquery', 'jquery-ui' ));

// Use AssetRender to compile and render the HTML tag
$render = new AssetKit\AssetRender($config, $loader);

$targetName = 'demo-page';
$render->renderAssets($assets, $targetName); // pipe html tags to output buffer, the targetName is optional.

现在只需从浏览器中加载脚本，它应该会工作。

您可以在example文件夹中简单地检查示例脚本。

注册资产

资产可以离线注册，这是为了减少在线开销。一旦您有了AssetLoader对象，您就可以通过调用register方法从资产清单文件路径注册一个资产。

$loader = new AssetKit\AssetLoader($config);
$asset = $loader->register("tests/assets/jquery-ui");

注册的资产将被添加到资产条目存储中，并将被缓存。

加载资产

当您想要渲染一个资产或编译一组资产时，您需要从条目存储中加载资产。

$asset = $loader->load("jquery-ui");

有时您只想加载资产的一部分，您可以在后面追加一个filetype字符串来过滤出您想要的集合。

$asset = $loader->load("jquery-ui:stylesheet"); // Asset with stylesheet collections only
$asset = $loader->load("jquery-ui:javascript"); // Asset with javascript collections only

要在资产中查找特定的集合，您可以为集合预定义一个ID，并在运行时使用该ID查找集合。

$asset = $loader->load("jquery-ui#darkness"); // Asset with darkness theme stylesheet collections only

高级用法

这会创建并初始化assetkit.yml文件

$ assetkit init --baseUrl=/assets --baseDir=public/assets --dir=private/assets assetkit.yml

其中--baseDir选项是资产将被安装到的地方。

其中--baseUrl选项是资产可以从前端浏览器加载的地方。

其中--dir选项是您存储私有资产文件的位置。

assetkit.yml是您的配置文件，它以YAML格式存在，您也可以直接修改它。

注册您需要的资产

$ assetkit add app/assets/jquery
$ assetkit add plugins/foo/assets/jquery-ui
$ assetkit add plugins/bar/assets/bootstrap

然后将资产资源安装到您设置的--baseDir中

$ assetkit install

有两种安装模式，链接和复制，为了简单地将资产文件复制到baseDir，我们使用默认的资产安装器。

要为baseDir符号链接资产，您可能需要传递--link标志。

然后将AssetKit API集成到您的PHP web应用程序中，只需几行代码即可（您可以在public/index.php示例中查看）

use AssetKit\AssetConfig;
// Please install php-fileutil extension for beter performance, 

// To use AssetCompiler, AssetLoader or AssetRender, we need to initialize AssetConfig object.
$config = new AssetKit\AssetConfig( 'config/assetkit.yml',array(
    // the application root, contains the assetkit.yml file.
    'root' => APPLICATION_ROOT,
    'cache' => new UniversalCache\ApcCache(array( 'namespace' => 'myapp_' ));
));

$loader = new AssetKit\AssetLoader( $config );

$compiler = new AssetKit\AssetCompiler($config, $loader);
$compiler->enableFstatCheck();
$compiler->defaultJsCompressor = 'uglifyjs';
$compiler->defaultCssCompressor = 'cssmin';

$assets = $loader->loadAssets(array( 'jquery', 'jquery-ui') );
$render = new AssetKit\AssetRender($config,$loader, $compiler);
$render->renderAssets($assets,'page-id');

渲染结果

<script type="text/javascript"  src="assets/demo/d95da0fbdccc220ccb5e4949a41ec796.min.js" ></script>
<link rel="stylesheet" type="text/css"  href="assets/demo/3fffd7e7bf5d2a459cad396bd3c375b4.min.css"/>

如有需要，从远程（例如git、github、hg或svn）更新资产资源。

$ assetkit update

完成之后，您可以将资产文件预编译成压缩的javascript/stylesheet文件。

$ assetkit compile --target demo-page jquery jquery-ui
Notice: You may enable apc.enable_cli option to precompile production files from command-line.
Compiling assets to target 'demo-page'...
Stylesheet:
  MD5:  9399a997d354919cba9f84517eb7604a
  URL:  assets/demo-page/9399a997d354919cba9f84517eb7604a.min.css
  File: /Users/c9s/git/Work/AssetKit/public/assets/demo-page/9399a997d354919cba9f84517eb7604a.min.css
Javascript:
  MD5:   4a09100517e2d98c3f462376fd69d887
  URL:   assets/demo-page/4a09100517e2d98c3f462376fd69d887.min.js
  File:  /Users/c9s/git/Work/AssetKit/public/assets/demo-page/4a09100517e2d98c3f462376fd69d887.min.js
Done

您也可以这样做

$ assetkit compile --target main --html-output head.php jquery

因此，在您的应用程序中，您只需简单一行代码

<?php require "head.php"; ?>

您还可以在模板中使用Twig扩展

<html>
    <head>
    {% assets "jquery", "jquery-ui" as "my-home-page" %}
    </head>
</html>

要检查所有编译的目标，您可以简单地运行

$ assetkit target

要将资产添加到目标，您可以运行

$ assetkit target add demo-page jquery jquery-ui bootstrap

要删除一个目标，您可以运行

$ assetkit target remove demo-page

设置您首选的默认压缩器

请注意，我们内置了uglifyjs压缩器。

$compiler->defaultJsCompressor = 'uglifyjs';
$compiler->defaultCssCompressor = 'cssmin';
$compiler->registerCompressor('uglifyjs', function() {
    return YourCompressor;
});

要使用YUI压缩器

YUI_COMPRESSOR_BIN=utils/yuicompressor-2.4.7/build/yuicompressor-2.4.7.jar \
    assetkit add assets/test/manifest.yml

过滤器

CoffeeScript过滤器

$filter = new AssetKit\Filter\CoffeeScriptFilter;

Sass过滤器

Scss过滤器

CssImportFilter

CssRewriteFilter

API

AssetConfig API

$config = new AssetKit\AssetConfig('assetkit.yml',array(  
    'cache' => true,
    'cache_id' => 'your_app_id',
    'cache_expiry' => 3600
));
$config->setBaseUrl('/assets');
$config->setBaseDir('tests/assets');
$config->setEnvironment('production');

$baseDir = $config->getBaseDir(true); // absolute path
$baseUrl = $config->getBaseUrl();
$root = $config->getRoot();
$compiledDir = $config->getCompiledDir();
$compiledUrl = $config->getCompiledUrl();

$config->addAssetDirectory('vendor/assets');

$assetStashes = $config->all();

$config->save();

AssetLoader API

$loader = new AssetKit\AssetLoader($config);

// load asset from a directory that might contains a manifest file,
// Note: Since you're going to put the assetkit.yml file 
//       In your VCS, you should use relative path instead of 
//       absolute path.
$asset = $loader->register("tests/assets/jquery");

// load asset from a manifest file directly, 
$asset = $loader->loadManifestFile("tests/assets/jquery/manifest.yml");

// load multiple asset at one time
$assets = $loader->loadAssets(array('jquery','jquery-ui'));

$jquery = $loader->load('jquery');
$jqueryui = $loader->load('jquery-ui');

// get all loaded asset objects
$assets = $loader->all();

// get all loaded asset objects by pairs.
//   array( 'name' => [asset object], ... )
$assetMap = $loader->pairs();

// check if we've loaded the asset by asset name
if( $loader->has('jquery') ) {
    // do something here.
}

$updater = new ResourceUpdater;
$updater->update($asset);

AssetInstaller API

$installer = new AssetKit\Installer;
$installer->install( $asset );
$installer->uninstall( $asset );
$installer = new AssetKit\LinkInstaller;
$installer->install( $asset );
$installer->uninstall( $asset );

AssetCompiler API

$asset = $loader->registerAssetFromPath("tests/assets/jquery-ui");
$compiler = new AssetKit\AssetCompiler($config,$loader);
$files = $compiler->compile($asset);

echo $files['js_url'];  //  outputs /assets/compiled/jquery-ui.min.js
echo $files['css_url']; //  outputs /assets/compiled/jquery-ui.min.css

在生产模式下，编译后的清单被缓存到APC中，要使AssetCompiler重新编译您的资源，您需要重启HTTP服务器以清除这些缓存。

默认情况下，我们不扫描文件修改时间，因为过多的I/O操作可能会减慢您的应用程序。

要自动重新编译您修改的资源，您可以设置一个选项使您的PHP应用程序扫描资源文件的修改时间来重新编译资源

$render = new AssetKit\AssetRender($config,$loader);
$compiler = $render->getCompiler();
$compiler->enableFstatCheck();

启用内置的过滤器、压缩器

$compiler->registerDefaultCompressors();
$compiler->registerDefaultFilters();

注册过滤器、压缩器

$compiler->registerCompressor('jsmin', '\AssetKit\Compressor\JsMinCompressor');
$compiler->registerCompressor('cssmin', '\AssetKit\Compressor\CssMinCompressor');
$compiler->registerFilter( 'coffeescript','\AssetKit\Filter\CoffeeScriptFilter');
$compiler->registerFilter( 'css_import', '\AssetKit\Filter\CssImportFilter');
$compiler->registerFilter( 'sass', '\AssetKit\Filter\SassFilter');
$compiler->registerFilter( 'scss', '\AssetKit\Filter\ScssFilter');

AssetRender API

这是编译/渲染资源HTML标签的最高级API，它通过AssetCompiler编译加载的资源。

$render = new AssetKit\AssetRender($config,$loader);
$render->renderAssets($assets,'demo');

Asset Twig 扩展

在前端页面中包含样式表和JavaScript

包含指定的资源

{% assets 'jquery' %}

包含多个资源

{% assets "jquery", "jquery-ui" %}

将多个资源包含到目标中

{% assets "jquery", "jquery-ui" as "jquery-all" %}

黑客行为

安装依赖项

$ git clone git://github.com/c9s/AssetKit.git
$ cd AssetKit
$ composer install

安装一些扩展来提高速度

phpbrew ext install github:sqmk/pecl-jsmin
phpbrew ext install github:c9s/cssmin

确保所有人员都在工作

phpunit

... 黑客黑客黑客 ...

再次运行测试

$ phpunit

确保命令运行正常

$ php bin/assetkit init --base-dir .... --base-url ....
$ php bin/assetkit compile --target mainpage jquery jquery-ui

重新编译命令行二进制文件

$ scripts/compile

测试编译的二进制文件，只需键入

$ ./assetkit

待办事项

  • watch命令（通过分割过滤进程来监视资源文件或目录）

设置XHProf

您应该从https://github.com/facebook/xhprof安装xhprof扩展

然后设置主机名xhprof.dev到您的xhprof_html目录。

然后运行

pear install -f phpunit/PHPUnit_TestListener_XHProf
phpunit -c phpunit-xhprof.xml

资源端口清单

manifest.yml文件

---
resource:
  git: git@github.com:blah/blah.git
asset:
  - filters: [ "css_import" ]
    css:
    - css/*.sass
  - coffee:
    - js/*.coffee
  - js:
    - js/*
    - js/javascript.js