Better WordPress Minify

Needless to say, JS and CSS files are very important to a website/blog and this plugin allows you to do one thing: deliver those files to your visitors more intelligently. This plugin uses Minify¹ — “a PHP 5 application that combines multiple CSS or Javascript files, removes unnecessary whitespace and comments, and serves them with gzip encoding and optimal client-side cache headers.”

Plugin Features

• Uses the enqueueing system of WordPress which improves compatibility with other plugins and themes
• Allows you to change various Minify configuration options by editing the config file directly
• Allows you to customize all minify strings
• Offers various way to add a cache buster to your minify string
• Gives you total control over how this plugin minifies your scripts
• Supports script localization (wp_localize_script()²)
• Supports RTL stylesheets
• Supports media-specific stylesheets (e.g. ‘screen’, ‘print’, etc.)
• Supports conditional stylesheets (e.g. <!--[if lt IE 7]>)
• Provides hooks for further customization
• WordPress Multi-site compatible (not tested with WPMU)

Plugin Usage

Using this plugin is rather straightforward. After you activate this plugin all your JS and CSS files should be combined and minified automatically. Scripts and stylesheets are combined in the same order they are enqueued, and footer media files will be combined and minified correctly in the footer, too.

Note: There are plenty of plugins or themes out there (mostly outdated ones) that don’t want to use enqueueing functions. In such case, you will have to use some rewrite rules to achieve the same minification effect. Please refer to the FAQ section for more details.

Using this plugin in a Multi-site environment requires no additional step (except for a Must-use installation). Keep in mind that some options are only available to network admins (i.e. caching settings) and all cached contents (minified and combined JS, CSS files from all sites in your network) are kept in just one single cache folder. Do not worry about duplication, though, Minify handles that very well.

Now if you want to manually minify additional media files, you can always use a wrapper function called bwp_minify() in your theme files, for example:

<link rel='stylesheet' type='text/css' media='all' href='<?php echo bwp_minify($src); ?>'></link>

The $src variable should be the same parameter you use with wp_enqueue_style or wp_enqueue_script functions.

Customization

Cache Busting

Did you ever notice a version number that is appended to every single link of your media’s source file when you use wp_enqueue_script() or wp_enqueue_style()? The link below is an example:

http://example.com/wp-content/themes/a-theme/style.css?ver=3.1

That can be considered one type of cache busting methods, i.e. force visitors’ browsers to download the correct version of your JS and CSS files, instead of using a cached version. This is indeed useful when you update a plugin or more importantly, update WordPress.

BWP Minify gives you three options, using either your WordPress’s current version, the cache folder’s last modified time, or just a custom number that you can type yourself. You can also append nothing at all if you wish. If you choose to use a custom number, be sure to change it whenever you modify the source files.

Controlling the positions of your scripts

No plugin is perfect and this one isn’t either. There are some Javascript library out there that you can’t just minify using Minify, the PHP library this plugin utilizes. In such case, the only option is to ignore that JS file and use a pre-minified version if available. To ignore a script, just copy the handle (not the filename!) and put it in the ‘Scripts to be ignored’ box on a separate line.

You can repeat the same operation with other positioning boxes, including ‘Scripts to be minified in header’, ‘Scripts to be minified in footer’ and ‘Scripts to be minified and then printed separately’ (there are scripts that can be minified but not combined and that’s why you will have to print them separately.) And for your information, with the release of version 3.1, WordPress will have a new admin bar on every page of your website/blog when you are logged in, using one CSS file and one JS file (both have the handle ‘admin-bar’). For that reason, by default this plugin put ‘admin-bar’ in the ‘Scripts to be minified and then printed separately’ box to prevent it from being combined with normal media files.

Please note that this does not apply to style enqueueing. To exclude certain CSS files simply use the snippet below (put it in your theme’s functions.php):

add_filter('bwp_minify_style_ignore', 'exclude_my_css');

function exclude_my_css($excluded)
{
	$excluded = array('handle1', 'handle2');
	return $excluded;
}

If you want to minify a CSS file directly (i.e. print it separately), use the bwp_minify_style_direct hook instead.

Only allow certain media files to be minified

As of 1.0.5, you will be able to ask BWP Minify to minify only certain files. This is useful when you would like to bundle BWP Minify with your theme and want to let your users choose which files to minify.

There are two filters provided for this purpose, one for styles, and one for scripts. You just have to return an array consisting of allowed handles, or all if all files are to be minified. For example:

add_filter('bwp_minify_allowed_styles', 'my_allowed_styles');
function your_filter()
{
	// If the user choose to minify css files from the theme only
	if ($theme_only)
		return array('handle1', 'handle2', 'handle3');
	// Otherwise return 'all' string
	return 'all';
}

Simply replace bwp_minify_allowed_styles with bwp_minify_allowed_scripts if you are targeting JS files instead.

Advanced Customization

Although BWP Minify is meant to be as simple as possible, it is still very powerful and of course, extremely customizable. Read on if you would like to make the most out of this plugin!

Configure Minify

One of the first things any BWP Minify user would probably want to do is to re-configure the Minify software itself (for people who are still confused, Minify is a separate PHP library that is bundled with BWP Minify). In order to do that, you will need to edit a file called config.php that can be located in wp-content/plugins/bwp-minify/min/ by default.

Config.php contains important variables that Minify uses to operate. You can freely change this file to suit your needs but make sure that you read the readme.txt file (which is located in the same directory) to understand clearly what each variable is about. Most of the time you might want to change the cache age ($min_serveOptions['maxAge']) as well as the cache directory ($min_cachePath). Take a look at this page for more advanced Minify configuration.

Now a question will probably pop up in your mind: “Will the changes I made lost when I update BWP Minify?” If you simply edit the config file in the plugin folder, the answer is certainly yes. To be able to save your changes, you must change the Minify URL (URL to the min/ directory).

Changing the Minify URL

The default minify URL of a normal WordPress installation should be something similar to:

http://example.com/wp-content/plugins/bwp-minify/min/?f=wp-includes/js/jquery/jquery.js,wp-content/plugins/someplugin/js/somejs.js&ver=3.1

The above URL might look ugly to some of you, but the worst thing is it doesn’t allow you to save your changes made to the config file. Fortunately, BWP Minify allows you to change this URL very easily. Just double click on the Minify URL input and you will be able to set it to anything you want:

Changing Minify URL

Of course it’s not possible to just change this setting to a non-existent min/ directory. In other words, you must point it to a different installation of Minify on your server. For example something like this will work: http://example.com/min/ (assuming that an installation of Minify library exists there.)

Changing the cache directory

Important Note: By default the cache directory for Minify is located in the same directory as the min/ folder, so if you change Minify URL, it is necessary to change the cache directory too, assuming that you haven’t changed it already.

Changing the cache directory actually involves two steps:

Step 1: Change the $min_cachePath variable in Minify’s config file as described in the Configure Minify section above. Set it to a folder that is writable, i.e. CHMOD to either 755 or 777, depending on which one works for you. If CHMOD 777 is the only option but you worry about security, you might want to put this .htaccess file to your cache folder:

<Limit GET POST PUT DELETE>
Order Allow,Deny
Deny from All
</Limit>

Step 2: To be exact, BWP Minify will function just fine if you feel lazy and decide to stop at Step 1. However, you will soon notice that the cache directory set in admin area appears out of date. As of 1.2.0 you can double-click on the input field to edit it, or filter bwp_minify_cache_dir hook in case you want to do it a programmer’s way .

That’s it! Sorry for all the boring details, it’s time for you to sit back and enjoy!

Known Issues

Minify itself has some limitations that I advise you to take a look: http://code.google.com/p/minify/wiki/CommonProblems (pay attention to the CSS @import issue).

To-do List

• Automatic script/style handle detection: you will no longer have to look for script/style handles, all will be put in a convenient dropdown box for you to choose! (1.3.0)
• Friendly Minify URL: no more question mark! (1.3.0)
• Role-based Minification: If you’re an admin and would like to debug your scripts, this option is definitely useful! (1.3.0)
• HTML Minification
• (this section is open for feature requests)

Hook References

• bwp_minify_cache_dir – Replace the default cache directory, used when you change Minify’s config.php (filter)
• bwp_minify_min_dir – Use this if you need to include BWP Minify in your project (filter)
• bwp_minify_allowed_styles – Use this to allow only certain CSS files to be minifed (filter)
• bwp_minify_allowed_scripts – Use this to allow only certain JS files to be minified (filter)
• bwp_minify_style_ignore – An array of handles to ignore (filter)
• bwp_minify_style_direct – An array of handles to be minified separately (filter)
• bwp_minify_script_header – An array of handles to be minified in header (filter)
• bwp_minify_script_footer – An array of handles to be minified in footer (filter)
• bwp_minify_script_ignore – An array of handles to ignore (filter)
• bwp_minify_script_direct – An array of handles to be minified separately (filter)
• bwp_get_minify_src - Check plugin codes for available variables (filter)
• bwp_get_minify_tag - Check plugin codes for available variables (filter)
• bwp_minify_get_buster (filter)
• bwp_minify_before_styles – Fire before your minified CSS files (action)
• bwp_minify_after_styles – Fire after your minified CSS files (action)
• bwp_minify_before_media_styles – Fire before your media-specific minified CSS files (action)
• bwp_minify_after_media_styles – Fire after your media-specific minified CSS files (action)
• bwp_minify_before_{position}_scripts – Fire before your minified JS files (position can be ‘header’ or ‘footer’) (action)
• bwp_minify_after_{position}_scripts – Fire after your minified JS files (position can be ‘header’ or ‘footer’) (action)

Contribute to this Plugin

This plugin is licensed under GPL version 3, and it needs contributions from the community.

Buy me some special coffees!

My plugins and support for them are free. If you like my work and could buy me some (special) coffees, I would be much appreciated! They might help with some overnight times debugging my plugins, you know.

Support, Feedback, and Code Improvement

• Please report bugs to the BWP Community.
• WordPress Plugin Repository: http://wordpress.org/extend/plugins/bwp-minify/ (don’t forget to rate this plugin, thanks!)

i18n (Translate the plugin)

If you are a translator, please help translating this plugin. Even if you aren't, you can become one, it is very easy and fun! If you want to know how, please read here: Create a .pot or .po File using Poedit.

References

1. http://code.google.com/p/minify/ [↩]
2. http://codex.wordpress.org/Function_Reference/wp_locali ... ize_script [↩]