Make Your WordPress Plugin Easy to Extend

As a WordPress developer it is a painful (and all too familiar) feeling of angst, when I find a plugin that does almost exactly what I want but the author has left no way for me to modify the behavior without changing their code.

Don’t Hack Core (or plugins)

A popular refrain in WordPress developer circles is don’t hack core, which means please don’t modify the core WordPress files. This is good advice because when a WordPress update is released, the update will overwrite your changes. This same advice applies to plugins. You should never hack a plugin (i.e. you should never modify the plugin code directly) because your changes will be overwritten on update.

When authoring a plugin there are a number of things you can do to make it easier for other programmers to modify the behavior of your plugin without modifying your plugin files.

Four Ways to Make Your Plugin Easier to Extend

I presented this topic at WordCamp Baltimore 2017 and the slides for my talk Making Your Code Easy To Extend talk are available online.

Along with my presentation, I created a small plugin to demonstrate these techniques called the Raptor Button WordPress Plugin. The README.md file includes examples of how the plugin can be extended.

Internationalization
Add filters
Add actions
Use templates

Internationalization (I18n)

Whenever you use a string in your plugin run it through a translation function, the easiest to use being __().

Instead of

# Do NOT do this.
$btn_txt = 'Get Raptor';

run the text through the __() function first.

$btn_txt = __(
    'Get Raptor',       // Text to translate.
    'fe-raptor-button'  // Plugin slug.
);

Just by making this change, you’ve made it possible for a determined developer to apply their own translation.

To make your plugin truly translation friendly so it can be distributed with translations, see my blog post Make Your Plugin Translatable.

Add Filters

I gave a talk on Making WordPress Filters Work for You at WordCamp Lancaster 2017. I’ve made available online both the slides and the code samples.

A filter allows outside code to modify a value in a plugin during execution.

The following code doesn’t do anything, it takes the value from $btn_txt and puts it right back into the same variable $btn_txt.

$btn_txt = $btn_txt;

We can add a filtering opportunity using the apply_filters() function. The following code is the same as above (it takes the value from $btn_txt and puts it back into $btn_txt) unless someone has code that “hooks into” this filter.

$btn_txt = apply_filters( 'fe_raptor_btn_txt', $btn_txt );

Hooking into this filter allows us to modify the value using our own function. For example adding this code somewhere (e.g. in your theme’s functions.php or in a mu-plugin), will modify the value in $btn_txt.

add_filter( 'fe_raptor_btn_txt', function( $btn_txt ) {
    return 'Click for a surprise!';
});

Add Actions

You can grant other developers the ability to execute their own code at a given point by adding a call to the do_action() function, with a unique identifying hook name.

do_action( 'fe_before_raptor_btn_template' );

Hooking into this action allows us to perform our own task during the execution of the plugin. This differs from filters in that no value is returned – we are not changing a value in the plugin, we are performing our own task.

For example adding this code somewhere (e.g. in your theme’s functions.php or in a mu-plugin), will echo this code before the plugin code continues.

add_action( 'fe_before_raptor_btn_template', function() {
?>
    <div class="alert alert-danger alert-dismissible" role="alert" style="margin: 10px;">
        <button type="button" class="close" data-dismiss="alert" aria-label="Close">
            <span aria-hidden="true">&times;</span>
        </button>
        <strong>Warning!</strong> Clicking this button could be scary.
    </div>
<?php
});

You can also make available additional values to the other code by adding them as parameters.

do_action( 'fe_stop_emails_log', $mock_email );

For an example of when I was able to help another developer extend one of my plugins through the use of an action hook, see Stop Emails Issue 10: Write email log in custom file.

Use Templates

I’ve written a separate blog post about just this topic, see Using Templates in a WordPress Plugin.

Photo Credit

Pixabay

Sal Ferrarello (@salcode)

Sal is a PHP developer with a focus on the WordPress platform. He is a conference speaker with a background including Piano Player, Radio DJ, Magician/Juggler, Beach Photographer, and High School Math Teacher. Sal can be found professionally at WebDevStudios, where he works as a senior backend engineer.