swCombinePlugin

This plugin combines javascript and stylesheet files into optimized files.

How it works ?

The plugin read all view.yml files and generates the correct combined files :

stylesheets
javascript

The plugin can also generate packages from a list of files. This feature allows you to create a common set of files for your website, and include specific assets for a view.

Benefits

Combine files and optimizations are performed when the application is deployed
The view cache file generates the correct path to the combined files, so there is not computation at runtime.

Available optimizers

Global
- swPassDriver : do nothing, use this if you want to combine your files with no optimizations
Javascript
- swDriverGoogleClosureCompilerApi : google closure algorithm (remote)
- swDriverGoogleClosureCompilerJar : google closure algorithm (local, require java)
- swDriverJSMin : JSMin algorithm
- swDriverJSMinPlus : JSMin+ algorithm
- swDriverYuiJs : YUI compressor (local, requires java)
Stylesheet
- swDriverCssmin : Css min algorithm
- swDriverMinifyCssCompressor : Minify Css Compressor algorithm
- swDriverYuiCss : YUI compressor (local, requires java)
- swDriverLessphp : Lessphp Less css implementation

Install

edit ProjectConfiguration.class.php by adding the requirement and enable the plugin

 [php] 
 require_once(dirname(__FILE__).'/../plugins/swCombinePlugin/lib/config/swCombineViewConfigHandler.class.php');
 
 class ProjectConfiguration extends sfProjectConfiguration
 {
   public function setup()
   {

      $this->enablePlugins(array(
         // your plugins
         'swCombinePlugin'
      ));
    }
 }

edit your app.yml and add an optional version value

 [yaml]
 swToolbox:
   swCombine:
     # the version number can be used to force load of new files from the media server
     #   you can configure a never ending expired time on your media server
     #   if the version is never updated, media will be never reloaded ...
     version: 3

add a config_handlers.yml inside APP/config

 modules/*/config/view.yml:
   # put sfViewConfigHandler to restore the default symfony config handler
   # class: sfViewConfigHandler
   class: swCombineViewConfigHandler 
   param:
    configuration:
      javascript:
        public_path:  /sw-combine/%SF_APP%
        private_path: %SF_WEB_DIR%/sw-combine/%SF_APP%
        combine:  swCombineJavascript
        driver:   swDriverJSMinPlus
        filename: %s.js                         # %s will by replace by the combined name
        exclude:
          - /js/jQuery/jquery.1.2.6.js
          - /js/jQuery/ui-1.5.3/jquery.ui.all.js
          - /js/jQuery/offset.js
          - /js/jQuery/jquery.form-defaults.js
          - /js/jQuery/jquery.timers-1.2.js
          - /js/jqModal/jqModal.js
          - /js/scrollTo/jquery.scrollTo-min.js
          - /js/main.js
        packages:
          common:
            auto_include: true                 # this will include the package on ALL pages
            files:
              - /js/jQuery/jquery.1.2.6.js
              - /js/jQuery/ui-1.5.3/jquery.ui.all.js
              - /js/jQuery/offset.js
              - /js/jQuery/jquery.form-defaults.js
              - /js/jQuery/jquery.timers-1.2.js
              - /js/jqModal/jqModal.js
              - /js/scrollTo/jquery.scrollTo-min.js
              - /js/main.js

      stylesheet:
        public_path:  /sw-combine/%SF_APP%
        private_path: %SF_WEB_DIR%/sw-combine/%SF_APP%
        combine:  swCombineStylesheet
        driver:   swDriverCssmin
        filename: %s.css                        # %s will by replace by the combined name
        exclude:                                # this will include the package on ALL pages
          - /css/main.css
          - /css/draft/ui-theme.css
          - /css/mg-theme.css
          - /css/print.css
        packages:
          common:
            auto_include: true
            files:
              - /css/main.css
              - /css/draft/ui-theme.css
              - /css/mg-theme.css

clear your cache
```
 ./symfony cc
```

combine css and js with

 ./symfony sw:combine frontend
 ./symfony sw:combine backend

update your templates files to use these helpers :

 use_helper('swCombine')
 sw_include_stylesheets()
 sw_include_javascripts()
 sw_combine_debug()

Packages

You can include packages into the view.yml, just add these lines into view.yml:

    all:
      sw_combine:
        include_packages:
          javascripts: [common]
          stylesheets: [common]

    myViewSuccess:
      sw_combine:
        include_packages:
          javascripts: [extra_code]

Assets version (optional)

This plugin has a hidden gem : asset versioning. When css files are combined, a version number is added to all externals references. This feature must be use with helper functions sw_include_stylesheets() and sw_include_javascripts(), this two helpers add the version number on each declared assets.

The asset version format is : ASSET_FILE?_sw=ASSET_VERSION

What does it mean ?

You can configure a long time expired value on your server by using simple regular expression.

(.*)\?_sw=(.*) => expired in 1 month.

Doing so, the user agent will not do any extras requests to the webserver.

Defining the asset version

edit your app.yml file by adding these lines

 swToolbox:
   swCombine:
     version: 42

clear your cache
```
  ./symfony cc
```

regenerate the combined css and js files with

  ./symfony sw:combine frontend
  ./symfony sw:combine backend

Troubleshooting

how can I set a media type for each package ?

for now this feature is not implemented.

css @import not loaded

the import syntax must be : @import url('yourfile.css') or @import url("yourfile.css").

this is not valid : @import url(yourfile.css)

Class swCombineViewConfigHandler not found

make sure the swCombineViewConfigHandler class is included in the ProjectConfiguration.class.php file

    require_once(dirname(__FILE__).'/../plugins/swCombinePlugin/lib/config/swCombineViewConfigHandler.class.php');

    class ProjectConfiguration extends sfProjectConfiguration
    [...]

unable to read the asset : /home/[...]/yourfile.css

All your css and js files must be relative, like /js/asds.js and /css/toto.css, the bad magic from symfony does not work

my background pictures get stripped out

The plugin uses css paths and sf_web_dir to find pictures, if the pictures do not exist then the plugin set none instead of url(non_existant_background), to avoid 404 requests on the webserver

rande/swCombinePlugin