filters

Moritz Mackiewicz edited this page Mar 9, 2017 · 39 revisions

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.

A note about compression filters

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);
    }
}

Built in filters

Javascript

  • 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.

  • ClosureJs A Google Closure Compiler adapter for compressing Javascript. This filter assumes you have Java installed on your system and that it's accessible via the PATH. You must also save the compiler.jar file in the vendors/closure directory.

  • 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.

  • 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.

  • 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.

  • 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.

  • JShrinkFilter connects with JShrink. You need to put Minifier.php into jshrink/Minifier.php, this is done by default by composer require tedivm/jshrink "@stable". You can use the path config option to choose an alternate path. It'll be applied when debug is off.

CSS

  • 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.
  • LessCss connects with LessCSS, allowing you to write css with LESS. Requires nodejs and less to be installed on your system.
  • 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.
  • ScssFilter connects with Sass, allowing you to use sass, and scss in your CSS files. Requires Ruby and the sass gem to be installed.

Filter API

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

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.

Filter Documentation

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

SprocketsFilter

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

//= require

//= 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

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.

JsMinFilter

No options.

CssMinFilter

No options.

YuiCss

Options:

  • path - Either the absolute path to YUICompressor, or the relative path to YUICompressor.

YuiJs

Options:

  • path - Either the absolute path to YUICompressor, or the relative path to YUICompressor.

LessCss

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

LessPHP

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

CoffeeScript

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

ScssFilter

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.

Uglifyjs

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