This class is designed to generate minified, merged, and automatically updating files to simplify the process of minified file usage and updating when going between production and development environments.
This class has four primary functions:
- Minification of single files
- $class->minify( 'sourcefile', 'outputfile', 'version' );
- Merging and minifying the contents of whole directories
- $class->merge( 'outputfile', 'directory', 'type [css, js]', array( 'items to exclude' ), array( 'files to merge and minify in order' ) );
- The output and minification may be specifically ordered by using the fifth and last parameter, with files passed as an array
- Only the files necessary to be prioritized here, and not every file in the directory
- Encoding image file data, replacing external image references within CSS
- Only applies to CSS files
- Default is false (image references are retained) (See "Basic Usage, item #1")
- Providing generated assets using gzip with specified cache control
- zlib Must exist and be enabled, otherwise no gzip will be used
- Default expires set to 30 days (60 x 60 x 24 x 31)
This class uses filemtime to determine if and when the minified version should be recreated, and will only create a new minified file IF a file selected for inclusion in the minify or merge functions is newer than the previously created minified file
Files that contain ".min." in the filename will not have their contents minified, but will still have their contents returned and added to compiled files as normal, as it SHOULD be assumed that those files have already been minified.
- JsMin as the default
- If the jsmin.php file is not found in the same directory as class.magic-min.php, it will be retrieved from github and created in the same directory automatically
- Google Closure
- To use google closure, add 'closure' => true to the class initation
##Basic Usage First, include and initiate the class. The class has been updated to use an array with up to 7 key -> value pairs, all accept boolean values or can be omitted entirely:
- Base64 encoded images (local or remote) can automatically replace file references during generation. This applies only to CSS files.
- 'encode' => true/false (default is false)
- url() type file paths beginning with "http" or "https" are retrieved and encoded using cURL as opposed to file_get_contents for local files
- Echo the resulting generated file path, or return to use as a variable
- 'echo' => true/false (default is true)
- Output the total execution time
- 'timer' => true/false (default is false)
- Output minified/merged assets using gzip with cache control
- 'gzip' => true/false (default is false)
- Use the Google Closure API as opposed to jsmin (jsmin is default)
- 'closure' => true (default is false)
- Retain or remove comments within file contents (Thanks to muertet for this one)
- 'remove_comments' => true/false (defaults to true)
- Generate hashed filenames based on file generation time. Allows for better cachebusting without the use of query string version numbers
- 'hashed_filenames' => false/true (defaults to false)
- 'output_log' => false/true (defaults to false)
- Brute force recompile merged and minified files for use during development
- 'force_rebuild' => false/true (default false, use sparingly!)
require( 'class.magic-min.php' ); //Default usage will echo from function calls and leave images untouched $minified = new Minifier(); //Return data without echo $minified = new Minifier( array( 'echo' => false ) ); //Echo the resulting file path, while base64_encoding images and including as part of css $minified = new Minifier( array( 'encode' => true ) ); //Return only AND encode/include graphics as part of css (gasp) $minified = new Minifier( array( 'encode' => true, 'echo' => false ) ); //Include images as part of the css, and gzip $minified = new Minifier( array( 'encode' => true, 'gzip' => true ) ); //Use google closure API, and gzip the resulting file $minified = new Minifier( array( 'gzip' => true, 'closure' => true ) ); //Use google closure API, gzip the resulting file, hash filenames, output to console $minified = new Minifier( array( 'gzip' => true, 'closure' => true, 'hashed_filenames' => true, 'output_log' => true ) );
Output a single minified stylesheet
<link rel="stylesheet" href="<?php $minified->minify( 'css/style.css' ); ?>" />
<script src="<?php $minified->minify( 'js/autogrow.js' ); ?>"></script>
Merge and minify the contents of an entire directory
<script src="<?php $minified->merge( 'js/packed.min.js', './js', 'js' ); ?>"></script> <link rel="stylesheet" href="<?php $minified->merge( 'css/master.min.css', './css', 'css' ); ?>" />
Output a minified stylesheet with a specified filename and ?v= param
<link rel="stylesheet" href="<?php $minified->minify( 'css/style.css', 'css/style-compressed.min.css', '1.1' ); ?>" /> //Will output: <link rel="stylesheet" href="css/style-compressed.min.css?v=1.1" />
<script src="<?php $minified->minify( 'js/jquery.reveal.js', '', '1.8' ); ?>"></script> //Will output: <script src="js/jquery.reveal.min.js?v=1.8"></script>
<?php $exclude = array( 'js/autogrow.js', 'js/autogrow.min.js', 'js/jquery.reveal.js', 'js/jquery.reveal.min.js' ); ?> <script src="<?php $minified->merge( 'js/packed.min.js', 'js', 'js', $exclude ); ?>"></script>
Get all the stylesheets in a directory and make a single minified stylesheet (excluding the ones used above)
<?php $exclude_styles = array( 'css/style.css', 'css/style-compressed.min.css' ); ?> <link rel="stylesheet" href="<?php $minified->merge( 'css/master.min.css', 'css', 'css', $exclude_styles ); ?>" />
###Viewing actions taken by MagicMin
If used, this function should only be requested after all other output has taken place by the magicmin script, ie...
Which would output to the console something such as:
Minifier Log : Timer enabled Minifier Log : Gzip enabled Minifier Log: timer : MagicMin processed and loaded in 0.00019097328186 seconds
This is the same as adding the 'output_log' => true param when initializing MagicMin
###Specifying the order of included files when using "merge"
Since it's simply not practical to assume glob() is going to determine dependencies, a fifth parameter exists for the merge() function.
In order to specify the order, you only need to specify the files that need to be ordered. You do not need to specify all the files in the directory, the function will automatically prioritize the files passed into the $order parameter.
<?php //Only exclude autogrow.js $exclude = array( 'js/autogrow.js' ); //Put jquery and validate before anything else $order = array( 'js/jquery.min.js', 'js/jquery.validate.js' ); <script src="<?php $minified->merge( 'js/magically-ordered.min.js', 'js', 'js', $exclude, $order ); ?>"></script>
###Including ONLY specified files in order, disregarding all others
As of 13-Jun-2013, the 3rd parameter of the ->merge() function will now accept an array of files to include. Files are included in the order specified in the array.
When using an array as the 3rd parameter (as opposed to the "css" or "js" file type), DO NOT include further parameters as this will create possible conflict.
<?php $include_only = array( 'css/base/jquery.ui.all.css', 'css/base/jquery.ui.base.css', 'css/base/jquery.ui.spinner.css' ); ?> <link rel="stylesheet" href="<?php $minified->merge( 'css/base/specified-files.css', 'css/base', $include_only ); ?>" />
NOTE: Files must be the same type (css or js) as different file types will not play nice in the output
##Usage within wordpress
For example (within header.php):
$dir = dirname( __FILE__ ); require_once( $dir .'/includes/class.magic-min.php' ); $min = new Minifier( array( 'echo' => false ) );
<link rel="stylesheet" href="<?php echo str_replace( $dir, get_bloginfo('template_directory'), $min->merge( $dir . '/css/master.min.css', $dir . '/css', 'css' ) ); ?>" />
Which would in turn output the correct URI to the stylesheet:
<link rel="stylesheet" href="http://yourwebsite.com/wp-content/themes/yourtheme/css/master.min.css" />
- Added brute force option to recompile minified assets
- Added output_log to configuration options to output to console automatically
- Bugfix to force arrays in minified_filedata requests
- Added support for protocol agnostic URIs such as '//ajax.googleapis.com/ajax/libs/...'
- Added plug and play function to simplify merge functionality
- Bugfix for merge functionality when using file list
- Altered minified_filedata to stored full list of files contained in minified package
- Added support for automatic re-minification when the number of files passed to the "merge" function changes