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:

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:

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.

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 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 enable compression on your CDN if possible (MaxCDN supports this as well), since Minify itself offers both compressed and uncompressed versions of minified contents based on appropriate request headers.

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.

Manage enqueued 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 not minify 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. 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 fully control each file. Options include:

For JS files:

Scripts to move to header: forcefully move the script to header

Scripts to move to footer: forcefully move the script to footer

Scripts to stay at original positions: used for scripts that cause issues when combined or moved from original positions (formerly known as Scripts to be minified and printed separately)

Scripts to not minify: used for scripts that cause issues when minified or already minified (formerly known as Scripts to be ignored (not minified))

Scripts to remove: used for duplicate scripts that you want to completely remove from your pages (formerly known as Scripts to be forgotten)

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 stay at original positions: used for styles that cause issues if combined or moved from original positions (formerly known as Styles to be minified and then printed separately)

Styles to not minify: used for styles that cause issues when minified or already minified (formerly known as Styles to be ignored (not minified))

Styles to remove: used for duplicate styles that you want to completely remove from your pages (formerly known as Styles to be forgotten)

As of 1.3.1, you are able to apply multiple controlling actions on an enqueued file. For example you can choose to move a JS file to header and also not minify it. Just select a JS file two times and select an appropriate action each time, e.g. “move to header” and then “not minify”, or you can just copy that JS file’s handle and paste it directly into each textbox.

If you allow an enqueued file to stay at its original position, all of its dependencies and their dependencies will also stay at original positions to avoid dependency issues, which means dependencies can only be minified but not combined.

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 not minify box and admin-bar, dashicons (since WordPress 3.8) into Styles to not minify 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:

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:

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:

<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!

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.