Get fresh WordPress Content delivered in your inbox with warpspeed!

learn wordpress wplift wordpress rocket

It was quite a while before I knew what Pluggable Functions were in WordPress, but when I learned boy did I see the power I had over new parts of the WordPress system.

This is the first post in a 3 part series on Pluggable functions. Today we’ll get an introduction to Pluggable Functions and provide a fairly simple example to show you exactly how they work and how you can use them in your themes. In the upcoming 2 posts we’ll look at logging many of the events in WordPress by using the pluggable functions available to us.

What are pluggable functions?

So what is a pluggable function? Well if you take a look in wp-includes/pluggable.php you’ll see a bunch of functions wrapped in a function_exists check. That means that if the function doesn’t already exist use the one inside the conditional.

By defining a function of the same name in your theme or plugin (typically a plugin is the proper spot for this) you can make core WordPress run your version of the function along with any additional code you supply. That means you can totally change how WordPress would normally deal with stuff like the emails that get sent automatically.

A simple example

Probably the most used Pluggable Function for me is wp_mail, which is what sends any of the emails in WordPress by default. I always use it to shut down automatic emails in my development environments (which we’ll cover in more detail in the second post). See I don’t want my clients customers getting automatic emails as I test things on my local machine, or on the development domain. I do want to know what’s happening so I log them, but no client should see the emails.

To simply shut them down we’d just add wp_mail to a standard plugin like you see below.

[sourcecode language="php"]
<?php
/*
Plugin Name: wp_mail Shut Down
Plugin URI:
Description: Shuts down wp_mail
Version: 1.0
Author: WP Theme Tutorial, Curtis McHale
Author URI: http://wpthemetutorial.com
License: GPLv2 or later
*/

/*
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/

if ( ! function_exists( 'wp_mail' ) ){

function wp_mail(){

} // wp_mail

} // function_exists

?>
[/sourcecode]

All we’re doing is is using a standard WordPress plugin header and then adding our own wp_mail function which does absolutely nothing. Notice that we also wrap our own custom function in a function_exists check. We do that because when our plugin is activated wp_mail does exist and our plugin will throw an error.

After our plugin is activated WordPress will load the plugin first, and our wp_mail function, then when it comes to the WordPress pluggable functions wp_mail will already exist so it won’t be run out of the WordPress core.

That means that all the automated emails in WordPress will be run through our function which does absolutely nothing. At least a customer won’t get them, but it’s not super useful for us yet. In our next post we’ll look at running wp_mail so that it logs all the emails that pass through wp_mail instead of actually sending them.

Building your own pluggable functions

Not only can you override WordPress pluggable functions, you can add them to your themes to allow other developers to easily override any custom functions you build in via a child theme. All you have to do is wrap any functions in your theme functions.php file in a function_exists check like you see below.

[sourcecode language="php"]
<?php
if ( ! function_exists( 'wptt_custom_breadcrumb' ) ){

function wptt_custom_breadcrumb(){

// output your breadcrumb code here

} // wptt_custom_breadcrumb

} // function_exists
?>
[/sourcecode]

Now if another developer creates a child theme of our theme and wants to override our breadcrumb function they just have to include it in the child theme. Since a child theme functions.php file is run before the parent the breadcrumb function will already exist and the parent version won’t be used.

Limitations and notes on Pluggable Functions

It should be noted that WordPress is no longer adding pluggable functions to core, so the current list in wp-includes/pluggable.php won’t get bigger. You can see a full list of the current pluggable function in the WordPress codex.

Also you can only redefine a function once. That means that 2 plugins that try to do different things with wp_mail using the method above won’t work at the same time. Which ever was loaded first will be used unless of course one of the plugins isn’t using a function_exists check, then you’re just going to get fatal errors.

Wrapping up

That’s it for today, we’ve covered how to use Pluggable Functions in WordPress to override core WordPress functionality and how to include your own pluggable functions in themes.

The second part of this series will walk through my development logging plugin to show you how I use wp_mail by actually logging all the emails that come out of WordPress instead of just stopping them from being sent.

About The Author

Curtis has been building WordPress sites for 5 years and specializes in eCommerce and Membership sites. You can find more of his writing on his personal site at Curtis McHale  or his WordPress tutorials at WP Theme Tutorial. When not up to his elbows in WordPress you can find him hanging out with his wife and daughter.

Published:

Last updated on:

This post is by a guest author, if you would like to submit a guest post to WPLift, we'd love to hear from you. Please get in touch.

Join 40,000 WordPress Astronauts
AND GET OUR LATEST CONTENT IN YOUR INBOX WITH WARPSPEED

We will never spam you.
close-link
siteground coupon
Get 60% Off the No. 1 WordPress Hosting!
Get 60% Off the No. 1 WordPress Hosting!