When you start developing WordPress sites, you will probably find that you are reusing some pieces of code for each and every site you create (e.g. hide dashboard widgets and hide menus from the client, so they don’t break their site). A popular option is to copy and paste these custom functions into the functions.php file of every theme you create. Why this is by no means a bad practice, I would like to suggest a better and more modular approach through the use of custom functions.
Note: I would recommend the following methods only for developers building sites directly for clients. For those building themes for general distributions it is better to put everything into functions.php or build a framework which would then be called from functions.php.
First of all, let’s take a look at all the options for including custom functionality into your themes. Then we take a look at why I think the 4th option is best. Here we go:
- Dump all your custom code into the theme’s functions.php file.
- Split your custom code into smaller PHP files and build a framework which you then include through a theme’s functions.php file.
- Create a normal plugin with all your custom code.
- Create custom functions plugins and place them into the mu-plugins folder.
Wait a bit, options 3 and 4 seem pretty similar, but what is that mu-plugins folder? We’ll see what this in a moment. Before we get to it, we should note that options 1 and 2 are pretty good and probably the best solution if you are building a one-off theme for general distribution or selling as a ‘premium theme’. But that is not the focus of this post, we are now considering where to place custom code that we use regularly when building client sites. An added plus of the last two options above is that if a client decides to switch to another theme, the functionality you added will not disappear as the code will still be available within the plugin. So options 3 and 4 are definitely more suitable. Let’s take a look at Option 4 and you will immediately see the advantages.
Creating a Custom Functions Plugin and Placing it into the mu-plugins folder
The “mu” in the
mu-plugins folder name stands for “must use.” What this means is that any plugins in this folder automatically run on all sites (single site or all sites on a multi-site install). There’s no need to activate them. They just run. This should feel familiar to those of you that are used to having code that just runs when adding it to your theme’s
functions.php.If you don’t already have a must-use plugins folder, go to the
wp-content directory on your WordPress install and create a sub-directory named
mu-plugins. Then, add your
my-custom-functions.php file to this directory. Your directory should look like the following:
As shown in the screenshot, there’s no “activate” link for the plugin. It’s already running on your site since it’s in the
If you visit your plugins page in the WordPress admin, you should see a new option named “Must Use” alongside your active and inactive plugins as shown in the following screenshot.
In order to create a custom plugin, you can create a new PHP file named my-custom-fuctions.php (just an example), and insert the following code in it:
<!--?php /** * Plugin Name: My Custom Functions * Plugin URI: http://yoursite.com * Description: This is an awesome custom plugin with functionality that I'd like to keep when switching things. * Author: Your Name * Author URI: http://yoursite.com * Version: 0.1.0 */ /* Place custom code below this line. */ /* Place custom code above this line. */ ?-->
The only downside to using this option is that you can’t deactivate the plugin without manually removing the file from your site using FTP or whatever other method you use for adding/removing files from your site. If this is a concern for you, you can create a normal plugin and drop it into the plugins folder as with all other plugins.
Why I love the Custom Functions + mu-plugin folder combo
- Gives you the ability to retain all custom functionality when switching to different themes.
- Easily update the plugin through the normal WP update mechanism (see below).
- Show your custom plugins in a dedicated section in WP-Admin.
- Plugins display their version number so you can easily see what version of custom code you are running on a particular site.
How to Make Your Custom Functions Update Automatically
If you’d like your custom functions plugin/s to update automatically, you can achieve this through the suggestions offered in this excellent post by W-Shadow.
The method outlined above is best when you are reusing code over and over again on different sites, so before putting any custom functions into your plugin make sure to ask yourself whether this functionality is just for a particular site or will definitely be used by all the sites you will be developing. I also like to create several custom function plugins in order to split the functions according to what they do. For example I might have a plugin that deals solely with customising the WP-Admin section, another used for hardening the WP install, and so on.
Are you already using such a setup? Do you have something even better? Let us know!
Update: WP Candy is also running a very intesting article on this topic.