This plugin provides a task to optimize web assets used in your project, typically for better frontend performances:
- CSS files will be combined and compressed using cssmin or the Minify CSS Compressor library
- Javascript files will be combined and compressed using JSMin, JSminPlus or the Google Closure Compiler API
- PNG web images will be optimized with pngout, advpng or pngcrush if installed and available on the system
- JPEG web images will be optimized with jpegtran.
- Of course you can create your own optimization drivers
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.
- PHP 5.2.4
- Symfony 1.2, 1.3 or 1.4
- PHP CURL extension enabled and available using the php command line for Google Closure Compiler support
- Optionally, these PNG image optimization programs:
- Optionally, this JPEG image optimization programs:
jpegtran(get it)
$ php symfony plugin:install -s beta npAssetsOptimizerPlugin
$ 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.
Edit your config/ProjectConfiguration.class.php file to enable the plugin:
<?php
class ProjectConfiguration extends sfProjectConfiguration
{
public function setup()
{
$this->enablePlugins(array(
// ... other plugin(s)
'npAssetsOptimizerPlugin',
));
}
}
You're done with the plugin installation, now you have to configure it.
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
jpeg_image: # JPEG images configuration section
enabled: false # status of optimization
class: npOptimizerJpegImage # the JPEG image optimizer class to use
params: # optimizer class configuration
driver: Jpegtran # driver name
folders: # folders to scan for JPEG files to optimize (.jpg & .jpeg)
- %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.
Important 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 or /css/main.css in the view.yml one.
For javascript: JSMin, JSMinPlus or GoogleClosureCompilerAPI.
For stylesheets: Cssmin or MinifyCssCompressor.
For PNG images: Pngout, PngCrush or AdvPNG.
For JPEG images: Jpegtran.
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
$ php symfony optimize:assets frontend --type=jpeg_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 launch:
$ 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
- adding or modifying a JPEG 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.
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.
By default the task will use the prod environment, because asset optimizations are traditionnaly used in a production context.
But in the example below, we'll configure the optimizer only for the dev environment:
dev:
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
all:
np_assets_optimizer_plugin:
enabled: false
Last, generate the new optimized javascript file with the optimize:assets task for the dev environment:
$ php symfony optimize:assets frontend --type=javascript --env=dev
- BC BREAK: the
optimize:assetstask now uses theprodenvironment by default - added an exception throw when the GoogleClosureCompilerAPI driver retrieves an error from a call to the service
- BC BREAK: added a mandatory
applicationargument to theassets:optimizetask, to avoid processing assets optimization from the wrong application configuration - fixed a bug which prevent to understand the
enabledconfiguration setting for optimizers - fixed a typo in the file name of the
npDriverAdvPNGclass
Many thanks to Pascal Borreli for the bug reports.
- BC BREAK: The accepted
typeoptions of theoptimize:assetstasks have been renamed and are nowall,javascript,stylesheetandpng_image - BC BREAK: Refactored drivers management, they now have their own classes
- Added
JSMinPlusjavascript optimization driver, based on JSminPlus - BC BREAK: Driver names now reflects the driver class name:
JSMindriver will use thenpDriverJSMinclassJSMinPlusdriver will use thenpDriverJSMinPlusclassGoogleClosureCompilerAPIdriver will use thenpDriverGoogleClosureCompilerAPIclass
- Added
MinifyCssCompressorstylesheet optimization driver, based on Minify - Added
AdvPNGandPngCrushPNG optimization drivers - Added more unit tests
- Initial release
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.