Categories
Guides Resources WordPress

WordPress Plugin Development Primer

WordPress is capable of just about anything with the right plugins, this is my primer on how to start building them!

WordPress Plugins

Over the years I have used my WordPress plugin development skills to help clients solve problems, create unique interfaces, access remote API’s, and even to create web based games and chatbots.

With the power of plugins you can quickly craft an effective MVP for market testing a more complex application, build an e-commerce storefront, create a new type of social network, and just about anything else you could imagine!

So how can you get started? Let’s build one!

Let’s add the words ‘Hello World’ to the page title, before WordPress sends it to the browser.

What you’ll need to start developing WordPress Plugins:

  • a working WordPress installation
  • a text editor or IDE
  • that’s all

The specifics don’t particularly matter but I personally use MAMP PRO and PHPStorm to do most of my development heavy lifting.

You’re free to mix it up if you prefer Nginx or Eclipse, I won’t judge you. The only thing you have to care about at this point is that your setup works for you.

Initial Setup

Keep in mind these steps may look different depending on your setup. When talking about directories I will try to use bash style syntax and markup to indicate paths, directory changes, and other basic file io operations.

Find your way to your wordpress installation directory, most of mine look a little like this:

/Applications/MAMP/htdocs/[WP_PROJECT_NAME]/

Make note of this location for later use and then navigate to:

[WP_ROOT]/wp-content/plugins/

This is where WordPress looks for all plugins by default, so let’s create our plugin directory and navigate into it.

mkdir ijae-hello-world
cd ijae-hello-world/

I am calling this plugin “ijae-hello-world” as an homage to every programming course, book, and tutorial I ever read growing up.

Naming conventions and best practices:

  • Use a unique prefix to prevent collisions with core WordPress functions and other plugins

The WordPress Plugin File Header

So how does WordPress know which files it needs to load? One of the files in the directory must have a special “header” – a PHP comment block at the top that has been specially formatted with details about the plugin.

WordPress considers this the “main” plugin file and will load it automatically when the plugin is active.

Name your main plugin file after the plugin, just like we did with the directory.

touch hello-world.php
vi hello-world.php

At the very least the plugin header needs to have your plugin’s name:

<?php
/**
 * Plugin Name: IJA Examples - Hello World!
 */

And since we’re just getting started we can pretend that’s the only option.

When you head to the Plugins page in wp-admin you should see “Hello World” in the list of available plugins, not yet activated.

Hello World, A WordPress Plugin

Now that we have our main plugin file and header it’s time to make our plugin actually do something.

A Quick Guide to WordPress Hooks

WordPress largely runs on events and notifications that you will leverage to add functionality.

WordPress calls these events “hooks” and they come in two flavors:

  • Actions
    • Actions tell plugins listening for them when to perform logic related to specific events
    • Do not always have parameters passed into callbacks
    • Do not usually return values
  • Filters
    • Filters ask the listening plugins to take a look at event-specific data and modify it as necessary
    • Receive parameters in callbacks
    • Return values

You’ll make use of actions and filters extensively when coding WordPress plugins so I’m not too worried about the nitty-gritty right now.

All you need to worry about is how to tell WordPress you’re listening for an event and what to do about it when it happens:

// Actions
// add_action( string $action_name, callable $callback, int $priority = 10, int $accepted_args = 1);

function init_callback() {}

add_action( 'init', 'init_callback'); // We don't need the extra params because the defaults are fine

// Filters
//add_filter( string $filter_name, callable $callback, int $priority = 10, int $accepted_args = 1);

function wp_title_callback(){} // We don't need the extra params because the defaults are fine

add_filter('wp_title', 'wp_title_callback');

Using WordPress Hooks to Modify the Page Title

Take a look at header.php in your theme to see if it has a title tag. If not: when you look through the template you’ll see a call to wp_head() which is a core function whose sole job is to fire the wp_head hook.

What does that mean?

Many themes use the WordPress function wp_title to output the title directly in header.php. If you search the theme you’ll find that just before the title tag is output to HTML it’s run through the wp_title filter (you may recognize ‘wp_title’ from our hooks example).

That means all we’d have to do is tell WordPress to listen for that hook and then return our modified title.

But what if you don’t see wp_title()? Your theme likely supports title-tag, which is a feature that allows WordPress to dynamically add the title. In that case we just listen for document_title_parts and modify the title parts before WordPress renders them to HTML.

Update your main plugin file like this:

function ijae_hello_world_wp_title_callback($title, $sep) {
    return "Hello World! {$sep} {$title}";
}
add_filter( 'wp_title', 'ijae_hello_world_wp_title_callback' );


function ijae_hello_world_document_title_parts_callback($parts) {
    $partsTitle = $parts['title'];
    $parts['title'] = "Hello World! {$partsTitle}";

    return $parts;
}
add_filter( 'document_title_parts', 'ijae_hello_world_document_title_parts_callback');

Load any page or post and you should see a friendly little greeting before every page title!

Wrapping Up Our Plugin

That’s it! You’ve taken your first official journey into WordPress plugin development. You’re now a plugin developer!

There’s plenty more to learn and do but this guide has introduced you to the most important concepts of making plugins for WordPress.

  • Give your plugin a unique name, and a unique slug
    • “IJA Examples Hello World” became ‘ijae-hello-world’ and ‘ijae_hello_world’ in folder and function names
  • Create your main plugin file
    • Best practices suggest both your plugin directory and main plugin file use your chosen unique slug
    • Include the WordPress Plugin Header at the top of this file, with at least the “Plugin Name” field
  • Add hooks and callbacks
    • Tell WordPress what your plugin is listening for, and what to do with it when it happens

The Completed WordPress Plugin

Putting it all together doesn’t take much work,so if you’ve been following along you’re already done. However, if you skipped to this part you can just copy and paste from below:

<?php
/**
 * Plugin Name: IJA Examples - Hello World
 */

function ijae_hello_world_wp_title_callback($title, $sep) {
    return "Hello World! {$title}";
}
add_filter( 'wp_title', 'ijae_hello_world_wp_title_callback' );


function document_title_parts_callback($parts) {
    $partsTitle = $parts['title'];
    $parts['title'] = "Hello World! {$partsTitle}";

    return $parts;
}
add_filter( 'document_title_parts', 'document_title_parts_callback');

1 reply on “WordPress Plugin Development Primer”

Leave a Reply

Your email address will not be published. Required fields are marked *