Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Combine stylesheets and javascripts files, with no computation at runtime
PHP
Branch: master
Pull request Compare This branch is 8 commits behind rande:master.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
config
lib
.gitignore
CREDITS
LICENSE
README.md
package.xml.tmpl

README.md

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)

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

Something went wrong with that request. Please try again.