AssetsCompiler
AssetsCompiler is module for ZF2 that help you managment your project static files.
For now it is responsible for combine and minifying CSS and Javascript files. It is
in development state and in near future more features will be released., (*1)
It provides zend console route script to compile selected files as bundles and view helpers
to automatically attaching bundles in your views. It can add files md5 to bundle file
names - to avoid browser file caching after changes., (*2)
As bundle we understack pack of js/css files. In development mode all files from bundle
are including to your site separately. In production - they are contacted and minimized to
single bundle file and included in this way., (*3)
Installation
- Add
"psychowico/assets-compiler": "dev-master"
to your composer.json
file and run php composer.phar update
.
- Add AssetsCompiler to your
config/application.config.php
file under the modules key.
Minifier
Minifier classes provides zend console route script to compile selected files as bundles
and view helpers to automatically attaching bundles in your views. It can add files md5
to bundle file names - to avoid browser file caching after changes., (*4)
Configuration
To make Minifier working you need declare your bundles lists and set your local directories.
Easiest way is copy .../Minifier/config/minifier.global.php.dist
file
to config/autoload/minifier.global.php
. Next you need proper fill configuration data
inside minifier
key. Most options have default values, you can found their
in .../Minifier/config/module.config.php
file., (*5)
-
js_adapter - js adapter configuration array
-
class - adapter class (probably from \AssetsCompiler\Minifier\Adapter\)
-
options - array of adapter options, you can read about them in "Adapters" section
-
css_adapter - css adapter configuration array, like above, (*6)
-
development_mode - boolean flag, if true our view helper will attach all files included
in bundles, one by one. If setted to true - it will attach one combined
file per bundle. Default is true., (*7)
-
persistent_file - bundles need store some data, it is done in xml file, you can specify
where this file will be save, relative to project root. Not required. By
default it use "./data/minifier/config.xml" file.
-
public_dir - you can define your public directory here, relative to project root. Not required,
By default it use "./public".
-
bundles - bundles configuration, can have js and css keys
Both, js and css configurations you can define by using this options:, (*8)
-
output_dir - output directory where bundles of this type will be saved, relative to
project public directory
-
list - list of bundles
List of bundles is a array where key is the bundle name, value is options array:, (*9)
-
filename - the bundle output filename pattern - by default it is '%s-%s'. First argument
is the bundle name, second - bundle included files md5 value. Not required.
-
sources - array of the bundle included files, pathes relative to project public directory
How to use
If you had configured your bundles and need combine and minify them just
run your public/index.php file with cmds:, (*10)
php index.php minify
, (*11)
It will do all job. To make it more easier and more intuitive you can create
bin folder in your project root directory. There create minify
file with
the following content:, (*12)
#!/usr/bin/php
headLink()
->prependStylesheet($this->basePath() . '/css/bootstrap-responsive.min.css')
->prependStylesheet($this->basePath() . '/css/bootstrap.min.css')
->appendBundle('css_bundle')
echo $this->headScript()->prependFile($this->basePath() . '/js/bootstrap.min.js')
->prependFile($this->basePath() . '/js/jquery.min.js')
->prependBundle('js_bundle');
?>
Bundle names are keys from above defined configuration,
for sample: 'minifier'->'bundles'->'js'->'list'->'js_bundle'., (*13)
Analogously you can use prependJsBundle, prependCssBundle methods:, (*14)
<?php
$this->prependJsBundle('js_bundle');
echo $this->headScript();
?>
Remember that entries will be really rendered when you will echo zf2 headScript view helper
or headLink in prependCssBundle case., (*15)
Now you can simply control that zend attach js/css files list, or just bundles files - but
changing development_mode flag in your Minifier configuration., (*16)
Adapters
By default Minifier code use ..\Adapter\Minify adapter. It use
matthiasmullie/minify php library, so you do not need
install any additional stuff to start working. But if you have more needs you can use others
prepared adapter or write you own.
We provided three aditional adapters:
1. \Adapter\Closure - using google Closure library, can compile only js
2. \Adapter\UglifyJS2 - using UglifyJS2 library, only for js
3. \Adapter\YUI - using YUI Compressor library from yahoo, can be use with js and css, (*17)
They all external tools and need some configuration to start working with them. All can be configured
in very similar way. In your configuration 'minifier' array you can add two keys, js_adapter for
javascript adapter and css_adapter for css adapter. They both should be arrays like in example:, (*18)
...
'minifier' => array(
'js_adapter' => array(
'class' => 'AssetsCompiler\Minifier\Adapter\UglifyJS2',
'options' => array(
'exec' => '/uglifyjs2/path/or/link/',
'flags' => array(
.. //additional compiler flags
),
),
),
)
In similar way you can configure css_adapter, just remember that some adapters support only js!
In exec param you need give your local path to library that you want use (Closure/UglifyJS2/YUI).
In flags you can add additional parameters that will be send to compiler, for sample if you define
flags like this:, (*19)
...
'flags' => array(
'--comments' => '',
'--define' => 'DEBUG=false',
),
...
uglify will be called in something like
uglifyjs2 file1.js file2.js -o output_file.js --comments --define DEBUG=false
., (*20)