The very same mechanisms that makes WordPress extensible can be used to make your plugin extensible as well. Most of the time this will mean action and filter hooks. As a plugin author, you are no doubt familiar with how these hooks work, since your plugin is using them to hook into WordPress. But what some newer developers may not realize is just how easy it is to provide your own hooks to extend the functionality of your plugin.

Where to add hooks

When you’re getting started with your plugin it may not be obvious where to add hooks, and that’s okay. If you already have a number of people using your plugin, then perhaps you may have already received requests from people wanting to add some kind of functionality to the plugin or change how something works. Oftentimes these changes are appropriate to add directly into your plugin, and you are most certainly encouraged to do so when it makes sense. But sometimes the request represents an edge-case… something that one individual is wanting to do, but is very likely not going to be useful to most people using your plugin. Even worse, making such a change may be confusing or even undesirable by other users. In these cases, see if you can provide the appropriate hooks to allow people to extend your plugin to suit their needs.

Extended Profile is a good example which provides quite a few hooks for people to extend. One of the core features of the plugin is that it allows you to output an hCard Profile on a page, like I have on the front page of willnorris.com. The plugin provides most of the common hCard attributes that we thought an individual might be interested in like name, website, address, telephone number, etc. To collect this data from the user, the plugin extends the standard WordPress Profile administration page. But we knew that users might already have a different plugin capable of providing this data, or that they may want to pull the data form some other source. Additionally, the hCard microformat supports a number of other attributes that we didn’t include in the plugin. In order to support these use-cases, we used a combination of action and filter hooks (mostly filters, in our case) to allow the hCard profile to be supplemented, or outright replaced. This is actually how I added the “Last Seen” geo data to my hCard, which pulls data from Brightkite.

As a general rule of thumb, action hooks are used to alert other plugins that you are at a particular point within a process. Perhaps that you’re about to begin doing something, or that you’ve just finished doing something which other code may care about. If you’re printing things to the screen, an action hook may be a good place to allow other plugins to print things as well at a very particular point in your plugin’s processing.

Filters are intended to allow other pieces of code to actually modify something that your plugin has done. As mentioned above, the Extended Profile plugin makes heavy use of filters to allow other plugins to modify various aspects of the generated hCard before it is printed to the screen. In fact, the plugin hooks into its own filters in order to provide most of the functionality, just like any other plugin would.

That last point is worth underscoring: hooks are not just for other plugins to use, you should be using them yourself. WordPress makes extensive use of its own actions and filters, just take a look at default-filters.php. This has a number of benefits — it allows you to keep your own code fairly clean and modular, but perhaps more importantly it allows other plugins to actually remove functionality they don’t want using the remove_action and remove_filter methods. When it comes to making your plugin extensible, being able to remove functionality is just as important as the ability to add it.

How to add hooks

Adding new action or filter hooks is deceptively simple — there is no registration of hooks, you simply call do_action or apply_filters as needed. A simplified version of what happens in the Extended Profile plugin might look like this:

function get_extended_profile($user_id) {
    // start output buffering
    ob_start();

    // call the action hook which actually builds the profile
    do_action('extended_profile', $user_id);

    // get buffered content
    $profile = '<div id="profile">' . ob_get_contents() . '</div>';
    ob_end_clean();

    // filter everything before returning
    return apply_filters('post_extended_profile', $profile, $user_id);
}

Here you can see both a custom action and filter being used, first to build the profile and then to filter it. When adding hooks to your plugin, its important to think about what data those hook functions may need in order to do something useful. For example, functions which hook into the ‘extended_profile’ action need to know the ID of the user the profile is being built for so that they can fetch the appropriate data. The same user ID is also passed to the ‘post_extended_profile’ filter for the same reason. With filters it’s important to remember that only the first parameter passed into the hooking functions gets filtered. You can certainly pass other data as well to provide context, but only the first one is filtered (which is actually the second parameter passed to apply_filters, since the first one is the filter name).

The real beauty of WordPress action and filter hooks is in how lightweight the entire system is. Calling a hook that has no registered functions returns almost immediately. And registering a function to a non-existent hook has basically no overhead, and absolutely no consequence… the function simply never gets executed. While you should certainly think through your plugin and add hooks at the logical points, don’t worry too much about adding too many. Consider this: on a standard, out of the box WordPress installation with no plugins activated, a page load can easily cause over 1,000 calls to do_action and apply_filter. Having your plugin add in a handful more is not going to have any kind of adverse effect on WordPress performance, and you will potentially make your plugin users much happier.

Custom Constants

Another way to expose additional functionality within your plugin is through the use of custom constants. This is generally most appropriate to enable advanced functionality that you don’t want to expose through the normal WordPress option pages. For example, suppose you have a plugin which makes API calls to some service. The URL for that API endpoint is constant, but you might want to allow it to be overridden for testing purposes. Use a PHP constant for your API URL, but check to see if it is already defined:

// near the beginning of your plugin
if ( !defined('MY_PLUGIN_API_URL') ) {
    define('MY_PLUGIN_API_URL', 'http://api.example.com/service'); // default value
}

// throughout the rest of your plugin, always use the constant
file_get_contents( MY_PLUGIN_API_URL . '?user=joe' );

In this way, the API URL can be overridden by defining the constant in wp-config.php:

define('MY_PLUGIN_API_URL', 'http://testing.example.net/test-service');

This is not as common as using action and filter hooks, but is still useful especially when you want to ensure that other plugins are not able to manipulate the value. Unless you do some additional checking, you never know what functions may be hooking into your filter or what they’re going to do with the value… in fact that’s kind of the point, you’re not supposed to know or care. But in cases where you want to allow the user to define a custom value, but also ensure that other plugins don’t manipulate the data in any way, constants are the way to go.

A final note if you do end up adding hooks or constants to your plugin. Because so many plugins aren’t able to be extended in these ways, it is well worth drawing attention to the fact in your plugin’s readme.txt. You can even go so far as to document all of the extension points as I did with the OpenID plugin, but you don’t necessarily have to. Just pointing out that hooks exist is often enough, developers can quickly scan your code for them.

echo '<script type="text/javascript">
    jQuery.get("' . plugins_url('my-plugin/ajax-handler.php') . '");
    // do something with AJAX data ...
</script>';

This is not a problem in and of itself, in fact it’s great that the plugin developer is actually using the plugins_url function! The problem arises in the my-plugin/ajax-handler.php file itself. If that plugin needs to make use of any WordPress data or functions, then the developer is certain to do something very ugly. You’ll know it when you see it:

require_once('../../../wp-load.php');

// or sometimes you'll see...
require_once('../../../wp-config.php');

So what is this, and why is it so bad? Well, the wp-load.php is a file provided by WordPress core that bootstraps the WordPress environment. It loads in the wp-config.php file, loads all the common WordPress functions and classes, initializes the database connection, and gets everything in place to process the request. These are all important things, and provides a lot of functionality that the plugin developer may need. The problem is that in the require_once call above, the plugin developer is assuming that the wp-load.php file is in a directory exactly three levels up in the filesystem from their plugin directory. In a standard WordPress deployment, this will be true and everything will work fine (for the most part). But as we’ve already seen, WordPress allows deployers to move where their wp-content or their plugins directory lives, so the above code will break completely. Yes, there are files in WordPress core that do something similar to the above, for example wp-admin/admin.php. But these are safe for WordPress core files because they do know where certain files will be. It is never safe to make this assumption from a plugin. I think it’s pretty safe to say that if you have a require or include call that goes up more than a couple of directories (“../../”), you’re almost certainly doing it wrong.

A couple of points to emphasize before moving on: if your plugin files are not accessing any built-in WordPress functions, classes, or data, calling them directly should be just fine. Also, if you’re doing AJAX calls on admin pages, use the built-in functionality WordPress core provides.

The Right Way

So the right way of doing this is actually pretty straightforward conceptually, but in practice there are a couple of ways to do it depending on your needs. The short answer is that instead of calling your plugin file directly, you must send the request through the standard WordPress request handling mechanisms. This requires two things: constructing your request properly, and then hooking into the WordPress request handling code at the appropriate time to take over the request handling yourself.

All standard WordPress requests eventually get broken down to a request to /index.php with a bunch of URL parameters. For example, when someone goes to your blog post at

http://example.com/2009/01/hello-world

WordPress uses the configured permalink structure to break this down to

http://example.com/index.php?year=2008&monthnum=01&name=hello-world

And from that, WordPress can determine which post the request is for, and serve that up accordingly. So what we want to do is be able to construct a request along the lines of

http://example.com/index.php?my-plugin=ajax-handler

and then hook into the WordPress request handling logic so that we can process this request ourselves. Fortunately, WordPress provides an action hook for exactly that purpose, called process_request. Functions that hook into this action are passed one parameter, an instance of the WP class, which encapsulates most of the specific parameters for the current request. If we want to process only the requests which include my-plugin=ajax-handler, we would add something like this to the plugin:

function my_plugin_parse_request($wp) {
    // only process requests with "my-plugin=ajax-handler"
    if (array_key_exists('my-plugin', $wp->query_vars) 
            && $wp->query_vars['my-plugin'] == 'ajax-handler') {

        // process the request.
        // For now, we'll just call wp_die, so we know it got processed
        wp_die('my-plugin ajax-handler!');
    }
}
add_action('parse_request', 'my_plugin_parse_request');

If you’re following along at home, try accessing http://example.com/index.php?my-plugin=ajax-handler. What happens? Most likely, nothing at all… it still loads your normal blog index page. So what went wrong? In order to have the WordPress request handling code process custom URL parameters, we have to register them. This is necessary for a number of reasons including security, performance, and also to ensure that WordPress doesn’t accidentally process something it wasn’t meant to. Fortunately, registering a new query variable is very simple using the query_vars filter hook:

function my_plugin_query_vars($vars) {
    $vars[] = 'my-plugin';
    return $vars;
}
add_filter('query_vars', 'my_plugin_query_vars');

This simply registers ‘my-plugin’ as a valid query variable to be processed by WordPress, but says nothing about valid values for that variable. So now try reloading the page, and you should be greeted with a simple styled page reading “my-plugin ajax-handler!”. Now you just need to modify the my_plugin_parse_request function to actually do your custom request logic, and you’re good to go.

I mentioned earlier that there are a couple of ways to do this. The one caveat to be aware of with the above approach is that you are hooking into the WordPress request processing logic before WordPress has processed the query itself. WordPress’s query handling logic is responsible for examining the request and figuring out what page or post within WordPress the request maps to. This is also what makes the is_* functions work: is_page, is_front_page, is_feed, etc. If your plugin is actually doing things on normal WordPress page requests and needs access to these functions, then instead of hooking into the parse_request action, you should use the wp action. You are still passed an instance of the WP class, so all you need to modify is the add_action call:

add_action('wp', 'my_plugin_parse_request');

I would recommend that you not make this change unless you know that you need to. Otherwise, you’re having WordPress perform a lot of logic that isn’t necessary (including hits against the database), potentially making the request take longer than it needs to be. Though the difference is likely to be imperceptible, it’s just good practice to keep things as fast as possible. And when dealing with custom request handling, you can keep things fast by hooking into as soon in the flow as possible.

Additional Exercise for the reader

If you don’t like the look of URL containing index.php?my-plugin=ajax-handler, and instead want something pretty like

http://example.com/my-plugin/ajax-handler

that is certainly possible with just a little bit more work (see WP_Rewrite). The WordPress OpenID Plugin does this to achieve nice endpoint URLs for the OpenID authentication protocol. A word of caution with this however: if you want to make sure that your plugin works on the widest number of deployments, where you have no idea what their permalink structure is going to be, there is a bit more work that is necessary. You can see the rewrite rules I setup for the OpenID plugin in the common.php file. There’s a lot of other stuff in there, and the rewrite code is a little confusing at parts, but it’s all there. I will actually be changing this in the future to simplify things a bit, so avoid complicating matters unless there is a real reason to.

Further codex reading:

• http://codex.wordpress.org/Query_Overview
• http://codex.wordpress.org/Custom_Queries

So what should plugins do instead? In order to make moving your content folder possible, WordPress 2.6 added a number of constants and functions which refer to the correct location of several often used folders. So instead of including an image using something like:

<img src="<?php bloginfo('wpurl') ?>/wp-content/plugins/my-plugin/images/logo.png" />

you would have:

<img src="<?php echo WP_PLUGIN_URL ?>/my-plugin/images/logo.png" />

or even better:

<img src="<?php echo plugins_url('my-plugin/images/logo.png') ?>" />

Since these constants were added in WordPress 2.6, they obviously won’t work in earlier versions. No problem, you can define them yourself in your plugin. The WordPress Codex page Determining Plugin and Content Directories includes 8 lines of code (plus 1 comment) that you can add to your plugin to ensure these constants are set, even in older versions of WordPress:

// Pre-2.6 compatibility
if ( ! defined( 'WP_CONTENT_URL' ) )
    define( 'WP_CONTENT_URL', get_option( 'siteurl' ) . '/wp-content' );
if ( ! defined( 'WP_CONTENT_DIR' ) )
    define( 'WP_CONTENT_DIR', ABSPATH . 'wp-content' );
if ( ! defined( 'WP_PLUGIN_URL' ) )
    define( 'WP_PLUGIN_URL', WP_CONTENT_URL. '/plugins' );
if ( ! defined( 'WP_PLUGIN_DIR' ) )
    define( 'WP_PLUGIN_DIR', WP_CONTENT_DIR . '/plugins' );

Everywhere else in your plugin, make sure that you use the constants, not the hardcoded path. If the string ‘wp-content’ appears anywhere in your plugin that isn’t defining one of the constants above, you’re doing it wrong. If you also want to make sure the functions like plugins_url are available in older versions of WordPress, see the compatibility.php file the ships with the WordPress OpenID Plugin.

So plugin authors, please go and fix this in your plugins. Please? Otherwise I can’t use your plugin at all on my site.