Making Your WordPress Plugins Developer Friendly

WordPress plugins are typically used by two groups of people: WordPress web site owners, and developers. It’s important to meet the needs of both sets of users.

Developers may be people with a basic level of WordPress / PHP knowledge, who want to tinker with your plugin. They may also be experienced WordPress developers who want to use your plugin to provide specific functionality to a client’s web site.

If you’d like an introduction to plugin development for WordPress, Tim Smith’s article WordPress Plugin Development is worth a read.

Why Make My WordPress Plugin Developer Friendly?

The main reason is you’ll help prevent developers from having to edit core plugin files to achieve the functionality they require.

In turn, this reduces the number of support requests and potential frustration from developers who make changes, only to find their changes are reverted in a plugin update.

Developer-friendly plugins also mean you’re more likely to get valuable feedback from more experienced developers, who may have extended your plugin’s functionality and are happy to provide their code enhancements. This allows your plugin to naturally grow, and become more stable, secure and useful to a larger audience.

There are several ways to make your WordPress plugins developer friendly, and today we’ll cover using WordPress’ Actions and Filters.

Actions and Filters: A Primer

One of the core features of WordPress is its Plugin API. Specifically, this provides Filters and Actions, also known as hooks, which ‘hook’ into WordPress’ core at specific places.

Actions

Actions allow us to run a specific function at a specific time. For example, if we wanted to send an email when somebody attempts to retrieve their password, we can use (or ‘hook’ on to) the retrieve_password action:

add_action( 'retrieve_password', 'my_plugin_retrieve_password' );

The first argument for add_action tells WordPress which action we want to hook on to. The second argument tells WordPress which function to call when the retrieve_password action is executed – in this case, we’d call the my_plugin_retrieve_password function.

Therefore, our code would be updated to include a function that does something when the retrieve_password action is executed:

add_action( 'retrieve_password', 'my_plugin_retrieve_password' );
function my_plugin_retrieve_password( $user_login ) {
    wp_mail( 'someone@example.com', 'Reset Password Attempt', $user_login . ' attempted to request a password reset.' );
}

Filters

Filters work in a similar way to Actions, except they allow us to modify the data that’s being returned, output or passed in a routine. For example, if we wanted to always prevent users from requesting a password reset email, we can hook on to the allow_password_reset filter, by registering our filter:

add_filter( 'allow_password_reset', 'my_plugin_allow_password_reset', 999, 2 );
function my_plugin_allow_password_reset( $enabled, $user_id ) {
    return false;
}

This returns false to the main variable in WordPress, which determines whether password reset requests can be executed.

Adding Actions and Filters in Your Plugin

Given that WordPress registers a number of Actions and Filters for developers to hook on to, it would be equally useful to register your own Actions and Filters within your plugin, for developers to also use.

There are two main ways of determining where to run Actions and Filters:

Common Requests for New Functionality

If your plugin has a number of requests for specific functionality, you might be tempted to simply add this into your plugin. However, if it’s only a minority of users wanting specific functionality, you’d add your actions / filters at that point in your plugin, and then produce code that could be run in a separate, standalone plugin which hooks into those actions and filters.

This allows developers and end users to get the functionality they require, without making large changes to your plugin’s core. It’s also a useful model to test drive new features as plugins, before merging them into your core plugin.

Code Extensibility

This one is a bit trickier. Developers tend to build solutions to short term, immediate problems. Good developers will also look to ensure extensibility, so that these solutions can be reused, scaled or extended in the future.

Wherever you see the potential for this to happen, but you don’t have a specific use case just yet, it’s time to insert an action or filter call.

A Real World Example

WordPress to Buffer Pro is a WordPress plugin which I’ve developed over the past few years. I received more and more requests to add or remove functionality – specifically, some developers wanted fewer scheduling options for their end users of the plugin, and some wanted more.

To meet the needs of all developers, and their end users, I built the following function:

/**
 * Helper method to retrieve schedule options
 *
 * @since 3.0
 *
 * @return array Schedule Options
 */
static public function get_schedule_options() {

    // Build schedule options
    $schedule = array(
        'queue_bottom'  => __( 'Add to End of Buffer Queue', 'wp-to-buffer-pro' ),
        'queue_top'     => __( 'Add to Start of Buffer Queue', 'wp-to-buffer-pro' ),
        'now'           => __( 'Post Immediately', 'wp-to-buffer-pro' ),
        'custom'        => __( 'Custom Time', 'wp-to-buffer-pro' ),
    );

    // Return filtered results
    return apply_filters( 'wp_to_buffer_pro_get_schedule_options', $schedule );

}

The key code here is the final line, where we return the result of the apply_filters call. By introducing apply_filters, WordPress will check for any registered filters in the WordPress theme or other plugins, which have been registered using add_filter.

If any filters are found, they’ll be executed at that point.

Therefore, whilst the array of schedule options are defaulted to 4, a developer can now build their own function, register it via add_filter and choose to only return 2 options:

add_filter( 'wp_to_buffer_pro_get_schedule_options', 'my_plugin_get_schedule_options', 10, 1 );
function my_plugin_get_schedule_options( $schedule ) {

    // Remove the 'custom' option from the scheduling options
    unset( $schedule['custom'] );
    return $schedule;

}

The add_filter call has two numeric arguments at the end:

• 10: This refers to the priority order to run this filter. If multiple filters are registered against this specific filter, they are then run in priority order, lowest to highest.
• 1: This refers to the number of arguments the function call can expect to receive. There will always be at least one argument – the variable we’re modifying – but in some cases filters may provide additional variables / data as well. In those cases, we would increase this number accordingly.

Actions work in a similar way; simply add do_action() calls to your plugin’s code where you’d like developers to optionally hook their own actions into:

function send_emails( $emails ) {
    // Some code here...

    // Allow developers to perhaps send their own emails too
    do_action( 'send_emails', $emails );
}

Developers can hook into this action using:

add_action( 'send_emails', 'my_plugin_send_emails', 10, 1 );
function my_plugin_send_emails( $emails ) {
    wp_mail( 'someone@example.com', 'Subject', 'Message' );
}

Conclusion

We’ve discovered how WordPress allows developers to hook into key actions and amend variables within the WordPress core, without making code changes to core code. From this, we’ve then extended the principles of Actions and Filters into our own plugin, to demonstrate how we can allow developers to modify and extend our plugin code, without making changes to our core plugin.

Next time, we’ll look at how to document Actions and Filters, as well as how to provide more developer-friendly documentation.