Download the PHP package corneltek/assetkit without Composer

AssetKit

AssetKit is designed for PHP's performance, all configuration files are compiled into PHP source code, this makes AssetKit loads these asset configuration files very quickly.

AssetKit is a powerful asset manager, provides a simple command-line interface and a simple PHP library with simple API, there are many built-in filters and compressors in it.

Concept

• To improvement the asset loading performance, we register these wanted asset manifest files into an assetkit configuration file, which contains the asset source directory and other manifest file information. the config file is converted into PHP source.

• When one asset is required from a web page, the asset can be quickly loaded through the AssetLoader, then the asset will be filtered through the filters and compiled/squashed to the front-end output. If the environment is production, the AssetRenderer will cache the url manifest for you, so you don't have to compile these assets everytime.

• In production mode, the asset compiler squashes the loaded asset files to the minified files.

• In development mode, the asset compiler simply render the include paths.

• You may define different required assets in each different page with a page id (target).

  The page id (target) is also used for caching results.

  So that in your product page, you may include jquery, product assets together with a page id "yourapp-products". And in your main page, you may include jquery, mainpage assets with a page id "youapp-mainpage"

• One asset can have multiple file collections, the file collection can be css, scss, sass, coffee-script, live-script or javascript collection.

• Each file collection may have its own filters and compressors. so that a CSS file collection can use "cssmin" and "yuicss" compressor, and a SASS file collection can use "sass" filter and "cssmin" compressor to generate the minified output.

• A "target" is consist of many assets, which is something like "page", we usually includes many assets in one single page, so called "target".

Why do we separately loading the different assets and define the asset manifest ? Because in the modern web application, most compononents are modularized, so in one application, there are many different plugins, modules, libraries, some plugins might provide its own assets, but some don't. some assets need to be compiled with some specific filters, but some don't. some assets need to be compressed through compressors like 'CSSMin' or 'JSMin', but some don't.

When developing front-end files, we usaually need to re-compile these asset files again and again, and at the end, we still need to re-compile them into one single squashed file to improve the front-end performance. And to re-compile these files, some people use Makefile, some people use Grunt.js, but it's still hard to configure, manage and distribute.

To give PHP applications a better flexibility, we designed a better archtecture to organize these asset files. that is, AssetKit.

Features

• Centralized asset configuration.
• Automatically fetch & update your asset files.
• AssetCompiler: Compile multiple assets into one squashed file.
• AssetRender: Render compiled assets to HTML fragments, stylesheet tag or script tag.
• Command-line tool for installing, register, precompile assets.
• CSSMin compressor, YUI compressor, JSMin compressor, CoffeeScript, SASS, SCSS filters.
• APC cache support, which caches the compiled manifest, so you don't need to recompile them everytime.
• Twig Extension support. (see below)

Requirement

• yaml extension.

Installation

Install the requirements:

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

Install library from composer:

Get the command-line assetkit:

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

Demo

The Asset Manifest File

To define file collections, you need to create a manifest.yml file in your asset directory, for example, the backbonejs manifest.yml file:

You can also define the resource, assetkit would fetch it for you. currently assetkit supports svn, git, hg resource types.

Basic Usage

Once you got assetkit, you can initialize it with your public path (web root):

The config is stored at assetkit.yml file.

Then fetch anything you want:

And your assetkit.yml file will be updated, these asset files will be installed into public/assets.

NOTE: To install asset files with symbol link, use --link option, Which is convenient for asset development.

If someone wants to clone your project, you can add assetkit.yml file to the repository, then B can do update command to update assets:

To use assetkit in your application, just few lines to write:

Now just load the script from your browser, it should work.

You may simply check example script in the example folder.

Registering Assets

Assets can be registered offline, this is to reduce the online overhead. Once you have an AssetLoader object, you can call the register method to register an asset from the asset manifest file path:

The registered assets will be added to the asset entry storage and will be cached.

Loading Assets

When you want to render an asset, or compile a collection of asset, you need to load the asset from the entry storage:

Sometimes you just want to load a part of the asset, you can append a filetype string to filter out the collections you want:

To find a specific collection in the asset, you can predefine an ID to the collection, and use the ID to look up the collection in the runtime:

Advanced Usage

This creates and initializes the assetkit.yml file:

Where the --baseDir option is the assets will be installed to.

Where the --baseUrl option is the assets can be loaded from front-end browser.

Where the --dir option is the location that you store your private asset files.

assetkit.yml is your config file, it's in YAML format, you can also modify it directly.

Register the assets you need:

Then install asset resources into the --baseDir that you've setup:

There are two modes for installation, link and copy, to simply copy assets files into the baseDir, we use default asset installer.

To symbol link assets to the baseDir, you may pass the --link flag.

Then integrate the AssetKit API into your PHP web application, there are just few lines to write (you may check the public/index.php sample):

The rendered result:

To update asset resource from remote (eg: git, github, hg or svn) if needed.

Once you've done, you can precompile the asset files to a squashed javascript/stylesheet files:

You can also do:

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

So that in your application, you can simple drop a line:

You can also use the Twig Extension in your template:

To check all compiled target, you may simply run:

$ assetkit target

To add assets to a target, you can run:

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

To remove a target, you can run:

$ assetkit target remove demo-page

Setting Up Your Preferred Default Compressor

Note that we've built-in uglifyjs compressor.

To use YUI Compressor

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

Filters

CoffeeScriptFilter

SassFilter

ScssFilter

CssImportFilter

CssRewriteFilter

API

AssetConfig API

AssetLoader API

AssetInstaller API

AssetCompiler API

When in production mode, the compiled manifest is cached in APC, to make AssetCompiler recompile your assets, you need to restart your HTTP server to clean up these cache.

We don't scan file modification time by default, because too many IO operations might slow down your application.

To auto-recompile these assets when you modified them, you can setup an option to make your PHP application scan the modification time of asset files to recompile assets:

To enable builtin filters, compressors:

To register filters, compressors:

AssetRender API

This is the top level API to compile/render asset HTML tags, which operates AssetCompiler to compile loaded assets.

Asset Twig Extension

Include stylesheets and javascripts in front-end page

Include specified asset:

Include multiple assets:

Include multiple assets to the target:

Hacking

Install deps:

Install some extensions to boost the speed:

Make sure all staff work:

... Hack Hack Hack ...

Run tests again:

Make sure command runs fine:

Re-Compile the command-line binary:

Test the compiled binary, simply type:

Todos

• watch command (fork filter process to watch asset files or directories)

Setup XHProf

You should install the xhprof extension from https://github.com/facebook/xhprof

Then setup hostname xhprof.dev to your xhprof_html directory.

Then run:

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

The asset port manifest

The manifest.yml file: