Justin Tadlock

Creating a custom functions plugin for end users

Most of the WordPress tutorials I write mention adding custom functions to your theme’s functions.php file. Many of the other tutorials around the Web will use this same technique for adding custom code. However, there are different ways of handling custom functions.

Telling a user to drop code in their theme’s functions.php file makes things easy for both the developer and the user. It’s easy to understand because nearly every theme has this file and users are accustomed to editing their theme rather than dealing with plugin code.

This tutorial will walk you through two plugin alternatives to using a theme functions file.

The big problem with editing themes

Before moving forward, you should know that there’s nothing wrong with adding custom code to a theme’s functions.php file, especially if the code is directly related to the theme you’re using. That’s not a problem at all.

The problem occurs when you add custom functions that aren’t necessarily tied to a theme such as when creating custom post types, taxonomies, or shortcodes. Most of the time, you’d want to keep these types of things separate from your theme because you’d like to retain the functionality when you switch themes.

Of course, you can transfer one theme’s functions.php code over to another theme, but why not make it even easier, requiring no transfer of code?

Creating a custom functions plugin

For the two methods described in this tutorial, you will need to create a custom functions plugin. This plugin will house all of your custom functions. Before doing anything else, create a file called my-custom-functions.php on your computer. Place the following code in this file.

<?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. */
?>

You can change the information at the top of this file to suit you. I prefer to leave the name as My Custom Functions so that I know it holds stuff that I’ve created.

Option #1: “Must-Use” plugin

Not many WordPress users are aware of what’s called the mu-plugins folder. WordPress doesn’t even ship with this folder by default, so it’s a bit of a hidden gem that I wish more folks knew about. Traditionally, it’s been thought of as part of the multi-site (old WordPress MU) setup by many people, but this folder works for single-site installs too.

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:

/wp-content
    /mu-plugins
        /my-custom-functions.php

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.

Custom plugin in the mu-plugins folder

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 mu-plugins directory.

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 worries you, follow along for another option.

Option #2: Regular plugin

If you’d rather have a plugin that you can activate/deactivate, you can create a regular plugin. The process is much the same as in the previous step. Rather than adding your plugin to the mu-plugins folder, you would add your my-custom-functions.php file to the plugins folder in the wp-content directory.

Your file and directory structure would look like the following:

/wp-content
    /plugins
        /my-custom-functions.php

If you visit the plugins screen in the WordPress admin, you’ll see My Custom Functions listed in your regular list of plugins as shown in the following screenshot.

Custom functions plugin on the WordPress plugins screen

Remember, this will behave like a regular plugin, so it won’t automatically run like a must-use plugin. You still have to activate it.

The biggest downside to this option is that the plugin is mixed in with all your other plugins. I prefer the separation of the mu-plugins folder for things that I plan to always have running on my sites.

Get started with your custom functions plugin

Every time you read a tutorial with something you’d like to do in WordPress, stop and think a moment before implementing its code if it asks you to add it to your theme’s functions.php file. Ask yourself the following questions.

  • Is this something I only want to happen when using my current theme?
  • Is this functionality I want to keep regardless of the theme I’m using?

If you can answer those two questions, you’ll know where the code needs to go.