Building an Object-Oriented WordPress Plugin (xkcd-shortcode) – Part 4

This is Part 4 of a Tutorial Series on building an Object-Oriented WordPress plugin from scratch.

Series Navigation:

  1. Design
  2. Making Remote Requests
  3. Generating HTML
  4. Connecting to WordPress’s Shortcode API
  5. Implementing Caching

In Part 3 you built the XKCDShortcode class that takes parameters from the user input and generates HTML from it. Along with the XKCDLoader from Part 2 you can now wire up this plugin to WordPress’s Plugin API.

Creating a Shortcode object

You need an instance of XKCDShortcode in the plugin class since it has the render method. Yet do you need it immediately? On every single page request?

No! You only need an instance of XKCDShortcode when a Post actually uses the [xkcd] shortcode. If the shortcode is absent the plugin isn’t used. And any objects that the plugin needs won’t be used as well.

This is an important principle to keep in mind. This is how you keep your plugin’s memory footprint to a minimum.

Don’t create objects until you need to use them.

With this in mind you’ll need a helper function to create a new instance of XKCDShortcode on demand. The first time the function is called an instance won’t exist so it will be instantiated. On subsequent requests the same object will be reused.

function getShortcode() {
  if (is_null($this->shortcode)) {
    $this->shortcode = new XKCDShortcode();
  }

  return $this->shortcode;
}

The add_shortcode callback

WordPress shortcodes are PHP functions that are hooked with the add_shortcode API.

You need a function that connects a WordPress add_shortcode callback function to your XKCDShortcode object’s render method. You will use the earlier getShortcode helper to do this in one fell swoop.

function callback($params) {
  return $this->getShortcode()->render($params);
}

When the first time this callback is fired, the shortcode object will get created and subsequently rendered. Dependent objects will not be initialized until then.

Registering Shortcode API Callbacks

Your design from Part 1 calls for enable and disable functions that trigger the registration with add_shortcode and remove_shortcode.

You could have done the same registration in the constructor as well. But having separate methods to do the registration has benefits.

In tests you want to ensure that this registration works reliably. To verify this you need to enable the plugin and then disable it, multiple times. With constructor embedded registration this is not possible. You can’t call the constructor manually.

Here are your registration functions,

function enable() {
  add_shortcode('xkcd', array($this, 'callback'));
}

function disable() {
  remove_shortcode('xkcd');
}

Setup the Main Plugin File

Everything is now in place. You only need to include the XKCDShortcodePlugin into your main plugin file. Add WordPress plugin headers and you are done!

/*
... Plugin Headers ...
*/
require_once(__DIR__ . '/lib/XKCDShortcodePlugin.php');

$xkcd_shortcode_plugin = new XKCDShortcodePlugin();
$xkcd_shortcode_plugin->enable();

Wrapping Up

You have made it this far, Well done! You’ve successfully built a completely Object-Oriented WordPress plugin from scratch!

Bonus

When designing and implementing this plugin you have overlooked one very important issue. Can you figure out what it is? Better yet post your solution below! Here’s a hint. Why was the food slow to arrive?

In the next and final part of this tutorial you’ll do a bit of refactoring to fix this issue.

Stay tuned for Part 5.

Level Up your WordPress-Fu with Weekly Tips in your inbox. Find out just why query_posts() is evil and why you should stop using it. (No Spam)