Back to Top

Better WordPress Minify

Better WordPress Minify

This plugin relies on WordPress's enqueueing system to minify your JS and CSS files, also provides friendly minify urls and CDN support.

 Sponsor   Themes by Elegant Themes - $39 for unlimited access to 80+ WordPress Themes!

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.

BWP Minify uses Minify1 — “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 move enqueued files to desired locations (header, footer, oblivion, etc.) via a dedicated management page (since 1.3.0)
  • Allows you to change various Minify settings (cache directory, cache age, etc.) directly in admin (since 1.3.0)
  • Allows you to use friendly Minify urls, such as http://example.com/path/to/cache/somestring.js (since 1.3.0)
  • Allows you to use CDN for minified contents (since 1.3.0)
  • Offers various way to add a cache buster to your minify string
  • Supports script localization (wp_localize_script()2)
  • Supports inline styles
  • 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

Plugin Usage

Basic Usage

Using this plugin is straightforward. After it is activated all your JS and CSS files should be combined and minified automatically. The enqueueing order and dependencies should be handled correctly.

Note: There are plenty of plugins or themes out there (mostly outdated ones) that do not 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, BWP Minify handles that 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:

  1. <link rel='stylesheet' type='text/css' media='all' href='<?php echo bwp_minify($src); ?>'></link>
<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. However it is highly recommended that you use those enqueueing functions instead.

Advanced Usage

There are some new advanced features added in version 1.3.0, two of which are Friendly Minify urls and CDN support.

Friendly Minify urls

This feature turns long and ugly Minify urls with query variables (such as http://example.com/wp-content/plugins/bwp-minify/min/?f=path/to/script1.js,path/to/script2.js), into more friendly ones (e.g. http://example.com/path/to/cache/somestring.js).

Friendly Minify urls feature is not turned on by default, and by enabling it BWP Minify will try to automatically update your server config file with required rewrite rules (either .htaccess file or nginx.conf, depending on which server you’re using).

If that succeeds, you should see friendly Minify urls being served right away, but if that fails, you will be given the choice to manually update your config files. Don’t worry, I tried to make that process as painless as possible.

By default, friendly urls are generated based on the URL path to Minify’s cache directory (e.g. /wp-content/plugins/bwp-minify/cache/). If you want to use a different URL path, for example you want to use your central caching directory in /wp-content/cache/bwp-minify/, follow these two simple steps:

  1. Go to BWP Minify > General Options, under Minify Library Settings, change Cache directory to /full/path/to/wp-content/cache/bwp-minify/. Hint: take a look at the auto-detected value to know your full path.
  2. Go to BWP Minify > Advanced Options, under Friendly Minify Urls, check if the Friendly Minify url path can be auto-detected. If it can’t be auto-detected (you will see an error message), you can manually set that setting to /wp-content/cache/bwp-minify/

As a rule of thumb, friendly Minify urls serve contents directly from Minify’s cache directory so you need to make sure your Friendly url path is a real path that is relative to your Site’s Address (not WordPress’s Address) and points to the actual cache directory. This is also true on a sub-directory multi-site environment, which means you would use your Network’s Address instead of an individual blog’s address.

If this feature doesn’t work for you, please refer to the FAQ section for some possible pointers.

Content Delivery Network (CDN)

It’s now possible to serve minified contents from your favourite CDN providers. This feature is not enabled by default either, but once your CDN hosts are properly configured, enabling it is a breeze.

You have the options to use one different CDN host for each file type, so one for JS files and one for CSS files. The primary CDN host will be used if you don’t specify any for a specific file type. You also have the option to use SSL all the time or use protocol-relative url (which works better in my opinion).

Enabling CDN support will have effect immediately so you should make sure that minified contents are CDN-ready. It is highly recommended that you enable friendly Minify urls prior to enabling CDN to make sure that your CDN’s Pull Zone can properly fetch minified contents on your site (not all CDN supports the default ugly Minify urls).

You should also be able to enable compression on your CDN if required, since Minify itself offers both compressed and uncompressed versions of minified contents.

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 four options, using either your WordPress’s current version, the cache folder’s last modified time, your current theme’s version, 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.

You can also set a buster using filters, for example:

  1. add_filter('bwp_minify_get_buster', 'bwp_minify_get_buster');
  2. function bwp_minify_get_buster($buster)
  3. {
  4.     return 'my-custom-buster';
  5. }
add_filter('bwp_minify_get_buster', 'bwp_minify_get_buster');
function bwp_minify_get_buster($buster)
{
    return 'my-custom-buster';
}

Controlling the positions of your files

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.

As of version 1.3.0 there’s a dedicated management page to manage your enqueued files, so you no longer have to manually look for file handles to re-position. The management page looks like this:

This page presents you with all enqueued files that have been detected by the plugin, and allows you to select a particular position for each file. Positions that can be used include:

For JS files:

  • Scripts to be ignored (not minified): used for scripts that cause issues or already minified
  • Scripts to be minified and then printed separately: used for scripts that cause issues if combined with other scripts
  • Scripts to be minified in header: forcefully move the script to header
  • Scripts to be minified in footer: forcefully move the script to footer
  • Scripts to be forgotten: used for duplicate scripts that you want to completely remove from your pages

Please note that if you move a script to a position (header or footer) that is not its original position, and there are other scripts that depend on it, all those dependent scripts will be moved to the new position too to correctly resolve dependencies.

For CSS files:

  • Styles to be ignored (not minified): used for styles that cause issues or already minified
  • Styles to be minified and then printed separately: used for styles that cause issues if combined with other styles
  • Styles to be forgotten (to remove duplicate style): used for duplicate styles that you want to completely remove from your pages

Prior to 1.3.0, you will have to use some filters to change positions of enqueued CSS files, that is no longer the case. Those filters are still available if you want to programmatically modify enqueued files’ positions. See the Hooks Reference section below for more details.

Last note: by default BWP Minify puts admin-bar, jquery-core, and jquery-migrate into Scripts to be ignored (not minified) box and admin-bar, dashicons (since WordPress 3.8) into Styles to be ignored (not minifed) to prevent those files from being minified and combined with other enqueued files, since those files are pre-minified and only used for logged in users.

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:

  1. add_filter('bwp_minify_allowed_styles', 'my_allowed_styles');
  2. function your_filter()
  3. {
  4.     // If the user choose to minify css files from the theme only
  5.     if ($theme_only)
  6.         return array('handle1', 'handle2', 'handle3');
  7.     // Otherwise return 'all' string
  8.     return 'all';
  9. }
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!

Minify’s config file

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). Minify works by using saved settings in a file called config.php that is located in wp-content/plugins/bwp-minify/min/ by default.

As of version 1.3.0, you can change various Minify settings directly inside BWP Minify > General Options page and BWP Minify will automatically save those settings to the config file if it is writable. If you, however, see this notice: “Notice: Minify config file /path/to/min/config.php is not writable”, that means the config file can’t be updated automatically. In such case, its auto-generated contents (based on settings you choose) will be printed on screen so you can update it yourself (update locally and upload via FTP, for example).

You can also directly modify the config file if you want 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. Take a look at this page for more advanced Minify configuration.

When you update BWP Minify inside WordPress’s Plugins page, your saved settings in the config file is lost. BWP Minify automatically re-applies your saved settings once the update is done, but only when the config file is writable. If you’re not that lucky, you will have to move your config file to a different location. See below for a possible solution.

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&amp;ver=3.1

That means your minified contents are served from this plugins’ min directory. However, there are cases when you want to serve minified contents from another location on your server (from your heavily patched Minify version for example), or, as stated above, you want to keep saved settings in Minfiy’s config file when BWP Minify is updated.

All you have to do is change URL path to Minify library setting under Plugin Functionality (BWP Minify > General Options) to a different location, and make sure that a Minify installation (the min directory) exists at that location.

Note that BWP Minify expects a URL path (e.g. /wp-content/min/) and NOT a fully qualified URL (e.g. http://example.com/path/to/min/) for the location you specified.

Minify’s document root

The Minify library requires a document root to function properly, and this is currently handled quite well. However there are cases when the document root is not properly configured, which leads to instant breakage for your website.

The term document root often refers to your server’s document root, but it is not necessarily the case here, as it is rather about WordPress’s document root, i.e. where WordPress’s index.php file resides. BWP Minify will use the highest level root, which is most of the time your server’s document root, but if that is not possible, your WordPress’s document root will be used.

You can also set a custom document root if you want (by changing the WordPress document root setting under Minify Library Settings (BWP Minify > General Options), but make sure that all your enqueued files live under such root. This is particularly useful when you want to combine and minify contents that are not related to WordPress (outside of WordPress’s directory).

BWP Minify expects an absolute path to your custom document root if you set one, of course.

Minify’s cache directory

Minify’s cache directory is where your combined and minified files are cached and stored. By default it is located in the same directory as the default min directory, i.e. /wp-content/plugins/bwp-minify/cache/.

You can make use of WordPress’s central caching directory where most plugins put their cached files, by changing Cache directory setting to your desired directory (e.g. /wp-content/cache/bwp-minify/), but make sure that the new directory is writable by your webserver.

Making your cache directory writable have two major benefits, one is Minify will be able to serve minified contents faster, and one is you can use the friendly Minify url feature (yes, that awesome feature won’t work if your cache directory is not writable).

On many servers this is handled automatically by your weserver so this should not be an issue. However on some servers you will have to change the permissions of your cache directory (i.e. CHMOD) to 777 (755 is usually the default). You might want to put the following .htaccess file to your cache folder:

  1. <Limit POST PUT DELETE>
  2. Order Allow,Deny
  3. Deny from All
  4. </Limit>
<Limit POST PUT DELETE>
Order Allow,Deny
Deny from All
</Limit>

for some added security. Note that there’s no GET before POST (prior to version 1.3.0 this was the case, and that will break friendly Minify urls).

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

  • Role-based Minification: If you’re an admin and would like to debug your scripts, this option is definitely useful!
  • 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 (deprecated in favor of bwp_minify_min_path)
  • bwp_minify_min_path – 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_style_oblivion – An array of handles to be removed (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_minify_script_oblivion – An array of handles to be removed (filter)
  • bwp_minify_get_src – Check plugin codes for available variables (filter)
  • bwp_minify_get_tag – Check plugin codes for available variables (filter)
  • bwp_minify_get_buster (filter)
  • bwp_minify_is_loadable – Return false to disable BWP Minify (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

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 []
Print Article Watch Log