We’ve talked about WordPress hooks before on this blog. And if you’re looking to modify the behavior of WordPress, a plugin, or theme, they’re your best option. They’re robust, they don’t break in the kind of conditions that “pluggable functions” might, and they’re the core way that WordPress plans to make itself easy to change moving forward.

All of that said, “pluggable functions” are still common in the WordPress world and so necessary for burgeoning developers to understand and be able to work with. They are, for example, still the prescribed way to change behaviors like the way WordPress sends emails. And there are numerous other examples in plugins and themes that you’ll run across. So let’s get to explaining!

In English, what do we mean by “pluggable function”?

Essentially, functions are a unit of action in a programming language. They’re ways to encapsulate (which is a fancy word for contain) a behavior so that you can call and reuse it throughout a program. A simple function may, for example, display the content of WordPress post, or take some input and return it decorated in some way — perhaps making a simple string of text into semantic HTML, for example.

What sets “pluggable” functions apart, is that they’re replaceable. If someone else has replaced the function — by declaring the same function before the “plugabble” function is loaded, their function becomes the one that is used by WordPress.

Let’s See A Pluggable Function!

Really, it’s not much to see. Rather than pull one of the few left in the core of WordPress I’ve made my own. Plugins and (parent) themes, perhaps even more than the WordPress core, are the places you’re actually likely to encounter these and need to use them, so my example’s a bit closer to that.

if ( ! function_exists( 'custom_function_to_add_p_tags' ) ) {
	function custom_function_to_add_p_tags( $between_p_tags ) {
		return '<p>'.$between_p_tags.'</p>'; 
    } 
}

As with most of my function examples, the actual job this function does is a bit silly, but it allows for me to make my point. Essentially if you find a function like the above in a plugin or theme that you’re looking to modify, you’re in luck. Because it’s a “pluggable function” — we can tell because of that if (! function_exists()) call around the function declaration — we can simply add to our theme’s functions.php file, or a custom plugin something like this:

if ( ! function_exists( 'custom_function_to_add_p_tags' )) {
	function custom_function_to_add_p_tags( $between_p_tags ) {
		return '$between_p_tags.'<br />'; 
    } 
}

Now where before there were <p></p> tags, which are used by HTML to delineate paragraphs, we’ll just get the line of text that would previously have been a paragraph followed by a line break (the <br />). Because our function, which gets declared before the pluggable function, has the same name it’ll be a one-for-one replacement with expected functionality. Now where this function was used, and wrapped paragraphs were the output, we’ll just see the text followed by a line break. Not the most sensible thing to do, but that’s the story.

Why do they look so similar?

The answer explains why pluggable functions aren’t being added to WordPress anymore: if many functions want to have an influence on an action, whoever gets there first gets 100% of the control, and no one else gets any say.

You may wonder, as I did when I first encountered an example like this, why both the original pluggable functions and our declaration look so similar. Why do both have that weird if ( ! function_exists() ) { thing, and and then declare the same function? Won’t they just be like two over-polite gentlemen stuck at a door, each waiting for the other to go first?

To answer that simply: no, they will not. Because one will always execute a fraction of second before the other, it’ll see no one waiting to go through the door and walk right in and declare itself. Then, because of that whole if clause PHP will stop the original pluggable function from coming in.

The other sensible question is why, given that, do we have to do that first check? The answer is exactly why pluggable functions aren’t something they’re adding to WordPress anymore. Essentially, if many functions want to have influence on an action, whichever one gets there first will have 100% of the control, and none of the others get any say. What this means, practically speaking, is that every declaration of a pluggable function must itself be pluggable. Because some functions could be so popular that many people are trying to replace them, without our check PHP will just shut the whole thing down because it can’t deal with two people in the same room going by the same name.

So while it is technically feasible for you to replace a pluggable function without the if () {} wrapper, there’s a real risk that you’ll break everything if some other guests are invited to the party you didn’t anticipate. This is a common occurrence with WordPress — there are so many plugins, and such a variety of themes — and those collisions do happen. This very reason of allowing for multiple modifications of the same functionality are why WordPress has wisely moved away from the model of “pluggable functions”.

(Plug photo by Gerwin Strum)