npAssetsOptimizerPlugin
This plugin provides a task to optimize web assets used in your project, typically for better frontend performances:
Combined javascript and css files will then replace original ones in the response, optionnaly with a timestamp appended as a GET parameter to force browsers to redownload them in case they're served with an Expires header and/or 304 HTTP status code, and if they've changed in the meanwhile.
Of course, the optimizations made and their use is configurable by environments, so you can enable the call for optimized assets only in prod for example. Each optimization process can also be disabled. See the Basic configuration section of this document to find out how to do so.
Everything is done by configuring some YAML by default, but the plugin architecture allows to easily extend the service and optimizers as well. See the Advanced configuration section of this document to find out how.
Prerequisites
Required
- PHP 5.2.4
- Symfony 1.2, 1.3 or 1.4
Optional
- PHP CURL extension enabled and available using the php command line for Google Closure Compiler support
- Optionally, these PNG image optimization programs:
Installation
Installation using PEAR
$ php symfony plugin:install -s beta npAssetsOptimizerPlugin
Installation using SVN
$ cd /path/to/your/symfony/project
$ svn co http://svn.symfony-project.com/plugins/npAssetsOptimizerPlugin/trunk plugin/npAssetsOptimizerPlugin
No need to say that if you're using SVN for your project, use the svn:externals property instead.
Basic configuration
Basic configuration of assets optimization is done in the np_assets_optimizer_plugin section of a standard app.yml configuration file. The plugin ships with a commented default one you'll find in the config folder of the plugin directory:
all:
np_assets_optimizer_plugin:
enabled: true # status of the plugin
class: npAssetsOptimizerService # the plugin service class to use
configuration: # optimization service configuration
javascript: # Javascript optimizer configuration
enabled: false # status of optimization
class: npOptimizerJavascript # the javascript optimizer class to use
params: # optimizer class configuration
driver: JSMin # javascript optimization driver name
destination: /js/optimized.js # destination path for optimized .js file
timestamp: true # adds a timestamp to the combined file url
files: # list of js assets to optimize and combine
- jquery.js
- jquery-ui.js
- application.js
stylesheet: # stylesheets configuration section
enabled: false # status of optimization
class: npOptimizerStylesheet # the stylesheet optimizer class to use
params: # optimizer class configuration
driver: Cssmin # stylesheet optimization driver name
destination: /css/optimized.css # destination path for optimized .css file
timestamp: true # adds a timestamp to the combined file url
files: # list of css assets to optimize and combine
- /facebox/facebox.css
- main
- skins/foo.css
png_image: # PNG images configuration section
enabled: false # status of optimization
class: npOptimizerPngImage # the PNG image optimizer class to use
params: # optimizer class configuration
driver: Pngout # PNG image optimization driver name
folders: # folders to scan for PNG files to optimize
- %SF_WEB_DIR%/images # by default, contains the web/images folder
Just create your own np_assets_optimizer_plugin in your application app.yml file to override these default settings.
Note: for the files section of both javascript and stylesheet optimizer configuration sections, the ordering of files is extremely important and should reflect the order used in your own view.yml files. Also, the very same syntax should be used: don't use main.css in the app.yml file where it's main in the view.yml one.
Available drivers
For javascript: JSMin, JSMinPlus or GoogleClosureCompilerAPI.
For stylesheets: Cssmin or MinifyCssCompressor.
For PNG images: Pngout, PngCrush or AdvPNG.
Usage
When you're done with configuration, you can launch the assets optimization task, which is available under the optimize namespace:
$ php symfony list optimize
The application argument is mandatory, whereas the type option allows to set the type of assets to optimize:
$ php symfony optimize:assets frontend --type=stylesheet
$ php symfony optimize:assets frontend --type=javascript
$ php symfony optimize:assets frontend --type=png_image
To optimize all assets in one call:
$ php symfony optimize:assets --type=all
To get full help on how to use this task, just lauch:
$ php symfony help optimize:assets
These tasks must be executed manually every time you make one of these changes:
- adding or modifying a CSS file handled by the plugin
- adding or modifying a Javascript file handled by the plugin
- adding or modifying a PNG image handled by the plugin
When optimized javascripts and css assets are generated, they aim to be used instead of the old ones. So you have to replace the calls to include_javascripts() and include_stylesheets() helpers in your layouts respectivelly by the include_optimized_javascripts() and include_optimized_stylesheets() ones, as shown in the example below:
<html>
<head>
<?php include_http_metas() ?>
<?php include_metas() ?>
<title>Foo</title>
<?php include_optimized_stylesheets() ?>
</head>
<body>
<?php echo $sf_content; ?>
<?php include_optimized_javascripts() ?>
</body>
</html>
Note1: Obviously, the optimized assets must have been generated before with the task for this to work.
Note2: Don't worry adding the npOptimizer helper to the default_helpers section of your setting.yml file, it will be automatically added at plugin configuration time.
Advanced Configuration
If you want to manage asset optimization by yourself, just extend the corresponding optimizer class; for instance, if you want to compress and combine javascript files your way instead of JSMin, JSminPlus or Google Closure Compiler ones, you can write your own driver by extending the npDriverBase class and implementing its abstract doProcessFile($file, $replace = false) method:
class npDriverMyDriver extends npDriverBase
{
public function doProcessFile($file, $replace = false)
{
// optimize javascript contents here...
if ($replace)
{
// replace file here
return $file;
}
else
{
// fetch contents from $file, optimize it, and return it
return $optimizedContents;
}
}
}
Don't forget to declare the new driver to use for javascript assets in your app.yml file. Here we'll take part of the environment feature of symfony and only configure the optimizer for the prod environment:
prod:
np_assets_optimizer_plugin:
enabled: true
class: npAssetsOptimizerService
configuration:
javascript:
enabled: true
class: npOptimizerJavascript
params:
driver: myDriver
destination: /js/optimized.js
timestamp: false
files:
- jquery.js
- application.js
Last, generate the new optimized javascript file with the optimize:assets task for the prod environment:
$ php symfony optimize:assets frontend --type=javascript --env=prod
Changelog
v0.8.1 - 2009-12-29
- BC BREAK: added a mandatory
application argument to the assets:optimize task, to avoid processing assets optimization from the wrong application configuration
- fixed a bug which prevent to understand the
enabled configuration setting for optimizers
- fixed a typo in the file name of the
npDriverAdvPNG class
Many thanks to Pascal Borreli for the bug reports.
v0.8.0 - 2009-12-25 (yes, x-mas release!)
- BC BREAK: The accepted
type options of the optimize:assets tasks have been renamed and are now all, javascript, stylesheet and png_image
- BC BREAK: Refactored drivers management, they now have their own classes
- Added
JSMinPlus javascript optimization driver, based on JSminPlus
- BC BREAK: Driver names now reflects the driver class name:
JSMin driver will use the npDriverJSMin classJSMinPlus driver will use the npDriverJSMinPlus classGoogleClosureCompilerAPI driver will use the npDriverGoogleClosureCompilerAPI class
- Added
MinifyCssCompressor stylesheet optimization driver, based on Minify
- Added
AdvPNG and PngCrush PNG optimization drivers
- Added more unit tests
v0.6.0 - 2009-12-21
Credits
This plugin is maintened by Nicolas Perriault. Patches and feedback are welcome, send them to nperriault at gmail dot com.
Some parts of the code it contains have been heavily inspired by Ryan Weaver's ioCombinerPlugin, many thanks to him for the great inspiration and discussions.
