filters - markstory/mini-asset GitHub Wiki

Mini-asset comes with several built-in filters. Filters are used to transform assets before and/or after they are concatenated together. Filters allow you to connect pre-processors like CoffeeScript, or LessCSS, as well as add minifiers like YUICompressor, or UglifyJs into your application. Filters are configured in the Configuration file.

Compression filters e.g. CssMinFilter, JsMinFilter etc. will only compress the output unless disabled. When integrating into your application, you can enable debug mode which will disable output filters. For example, if your application had an IS_DEBUG constant, you could extend the Factory and redefine the compiler method:

namespace App;

use MiniAsset\AssetCompiler;
use MiniAsset\Factory as BaseFactory;

class Factory extends BaseFactory
{
    public function compiler($debug = false)
    {
        return new AssetCompiler($this->filterRegistry(), IS_DEBUG);
    }
}

• ClosureJs A Google Closure Compiler adapter for compressing Javascript. This filter assumes you have Java installed on your system and that it's accessible
• CoffeeScript Integrates with coffee-script allowing you to easily write code in coffeescript. Requires both nodejs and coffee-script to be installed on your system. via the PATH. You must also save the compiler.jar file in the vendors/closure directory.
• Hogan Provides precompilation for mustache templates with hogan.js. Compiled templates will be inserted into the window.JST global. The keyname of the template will be the pathname without the extension and directory separators replaced with -.
• JShrink Allows you to minify Javascript files through JShrink. JShrink can be downloaded at https://github.com/tedivm/JShrink.
• JSqueeze Minify Javascript with https://github.com/tchwork/jsqueeze.
• Sprockets Provides a pre processing step that inlines dependencies using special comments. Comments of //= require <file> or //= require "file" are replaced with the contents of the required file. Includes done with "" imply that the file is in the same directory as the current file, whereas files included with <> imply that Mini-Asset should search all the defined javascript paths for the file.
• Typescript Runs input files through tsc capturing the generated Javascript code.
• Uglifyjs Uses uglify-js to minify javascript. Requires nodejs and uglify-js to be installed on your system. Like all output filters, UglifyJs will only be applied when debug is off. On windows, be sure to set the path to the js file inside node_modules/bin as you will have issues using the shell script or cmd file.

• YuiJs connects with YUI compressor. The jar file for yuicompressor, should be in vendors/yuicompressor/yuicompressor.jar by default. You can use the path option to define a different path. Like all output filters, YuiJs will only be applied when debug is off.
• JsMinFilter connects with the JSMin. You should put JSMin in vendors/jsmin/jsmin.php by default. You can use the path config option to choose an alternate path. Like all output filters, JsMin will only be applied when debug is off. JsMinFilter is deprecated and should not be used, as JSMin is unmaintained. Use UglifyJs instead.

• CssCompressor Minify CSS with node-css-compressor.
• ImportInline Will inline @import() statements in CSS files.
• LessCss connects with LessCSS, allowing you to write css with LESS. Requires nodejs and less to be installed on your system.
• LessDotPHP Pre-process LESS files with oyejorge/less.php.
• Minify Allows you to filter CSS/JS files through matthiasmullie/minify.
• ScssFilter connects with Sass, allowing you to use sass, and scss in your CSS files. Requires Ruby and the sass gem to be installed.
• ScssPHP SCSS pre-processor written in PHP. Requires scssphp/scssphp to be installed.
• SimpleCssMin Very basic CSS minifier implemented by mini-asset.
• TimestampImage Adds querystring parameters to background images in CSS based on the image timestamp.

• CssMinFilter connects with CssMin. The CSSMin library should be placed in vendors/cssmin/CssMin.php by default. You can configure this using the path option. Like all output filters, CSSMin will only be applied when debug < 2.
• YuiCss connects with YUI compressor. The jar file for yuicompressor, should be in vendors/yuicompressor/yuicompressor.jar by default. You can use the path option to define a different path. Like all output filters, YuiCSS will only be applied when debug < 2.
• LessPHP connects with LessPHP, allowing you to write css with LESS without having to install nodejs. LessPHP should be installed as a submodule git submodule add https://github.com/leafo/lessphp.git app/Vendor/lessphp.

There are a number of built-in filter that cover both pre and post processing. Filters generally implement one or both of the following methods:

• input($filename, $contents) Used to pre-process files before they are concatenated. This is a good place to integrate processors like CoffeeScript, Sass, or LessCSS. input() is called once for each file that is part of build target. It should return the altered file contents.
• output($filename, $contents) Used to post-process a concatenated file. This is a good place to apply minifiers such as YUICompressor, or Google Closure Compiler. This method is called once for the build file being generated. It should return the altered file contents.

Creating your own filters is pretty easy and just needs you to create a filter class that implements the MiniAsset\Filter\FilterInterface. This interface requires 4 methods:

• settings($settings)
• input($file, $contents)
• output($file, $contents)
• getDependencies(AssetTarget $target)

You can also extend MiniAsset\Filter\AssetFilter which includes empty methods for the interface. You can use the filters provided in the library as an example. Once your filter is complete, you can reference it in your config file using the full classname.

Individual filters provide additional features you can use in your assets. Specific filters accept different configuration options as well.

Mini Asset implements several features from sprockets. This helps you write more manageable source code with less insanity.

//= require allows you to create dependencies between to javascript files. It works very similar to how require works in PHP. Files can be required in from any of the paths[] configured in your ini file. Each file will only be included once into each build file by Mini Asset, so there is no need to worry about double including a file into a build file.

There are two flavours of //= require. The first is same directory requiring, which loads other files from the same directory or higher directories from the current file.

//= require "other_class"

Will inline ./other_class.js where the require statement was. other_class.js will also be processed for any require directives as well. The second type of require is all directory requiring. All directory requiring will include the first file with the matching name on any of the defined paths[].

//= require <my_library>

Would include the first my_library.js file found on any of the paths.

Note The provides directive supported by sprockets is not implemented by Mini Asset.

ImportInline inlines CSS import statements. Statements like @import('reset.css'); will be replaced by the contents of the named file. Paths are relative to the current file.

Options:

• ext The name of the extensions that should be treated as less files. Defaults to .less
• node The path to your nodejs executable. Defaults to /usr/local/bin/node
• node_path The path where you installed LessCSS with npm. Defaults to /usr/local/lib/node_modules

Options:

• ext The name of the extensions that should be treated as less files. Defaults to .less
• path The path where you installed LessPHP. Defaults to lessphp/lessc.inc.php

Options:

• ext The name of the extensions that should be treated as coffeescript files. Defaults to .coffee
• node The path to your nodejs executable. Defaults to /usr/local/bin/node
• coffee The path to your coffeescript executable. Defaults to /usr/local/bin/coffee
• node_path The path where you installed CoffeeScript with npm. Defaults to /usr/local/lib/node_modules

Options:

• sass The path to the sass executable. Defaults to /usr/bin/sass.
• ext The extension of files to run through sass. Defaults to .scss.

Options:

• node The path to your nodejs executable. Defaults to /usr/local/bin/node
• node_path The path where you installed uglifyjs with npm. Defaults to /usr/local/lib/node_modules
• uglify The path where npm installed uglifyjs. Defaults to /usr/local/bin/uglifyjs