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

Series Navigation:

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

WordPress Plugin Development can be a little formidable at times. There are hundreds of actions and filters to interact with. Bringing them together in a meaningful way into a Plugin is a challenge.

Yet putting all the functions of a plugin into a single PluginClass and calling it a day isn’t what Object-Oriented development is about. When it comes to OO, WordPress can sometimes seem at odds with the rest of the PHP community. It does not have to be this way.

In this five Part tutorial you will go about building an Object-Oriented WordPress plugin from scratch.

The WordPress Plugin you will be building is called xkcd-shortcode. The plugin embeds a specific numbered XKCD comic into a Post using the shortcode syntax [xkcd]. The image is embedded along with it’s alt and title text. Here’s what the finished version looks like,

Update  

How It Works

When a user uses the shortcode [xkcd num='10'], the 10th XKCD comic is embedded into that Post. The comic and it’s meta information like title and alt text is loaded from the XKCD.com using it’s JSON API.

A Few Things You Will Need To Know

1. wp_remote_get

To load JSON from the XKCD servers you will use WordPress’s wp_remote_get function. You could also have used the native PHP file_get_contents, but wp_remote_get offers an abstraction that compensates for older versions of PHP that may not have this feature. This is nice because in this plugin the internals of how the request is executed are not important.

2. wp_remote_retrieve_body

wp_remote_retrieve_body goes hand in hand with wp_remote_get. It extracts out the response body text received from the xkcd.com server.

3. json_decode

You will use json_decode to convert the response returned from the server into a native PHP object that is simpler to work with.

4. add_shortcode

Finally for the WordPress integration you need the add_shortcode function to register the [xkcd] shortcode and its callback. For the sake of completeness you will also use remove_shortcode which deregisters a shortcode. This will also improve the testability of the plugin.

The Feature List

It might seem that there isn’t much happening in this plugin at the moment. It would be tempting to just write up a quick-and-dirty add_shortcode callback function and be done with. However there are a number of things that need to be implemented to make this plugin work reliably. Here are the features you need to build.

  • The shortcode [xkcd num=5] should generate HTML to embed the corresponding XKCD.
  • The shortcode [xkcd] should generate HTML for the current/latest XKCD.
  • You need to link back to the original page to abide by the Creative Commons license.
  • An invalid XKCD number should show an error to the user.
  • You need to ensure that the plugin doesn’t blow up if the request to the xkcd.com servers failed for some reason.
  • You also need to handle any JSON decoding errors that could break the plugin.

Separation of Concerns

Looking at the feature list, one feature that stands out is the need to have a piece of code that fetches the JSON for a specified XKCD number. This code is independent of the rest of the plugin. For instance loading the JSON is not dependent on how the add_shortcode callback is registered. Once the JSON is loaded you have enough information to build the HTML from it.

Since this is a shortcode plugin, you also need to write a function that takes the shortcode attributes and returns the generated HTML. This is a good place to also add defaults for the shortcode. For instance you want to show the latest XKCD if num is not specified.

Finally you need to wrap this up to prevent collision with other plugins and WordPress Core function names.

Let’s split these 3 parts of the plugin into the Objects, XKCDLoader, XKCDShortcode, XKCDShortCodePlugin. Here’s an overview of what these objects would do.

XKCDLoader

This object has a load method that takes a number and fetches the JSON from the XKCD.com server. It returns a valid JSON object if the loading was successful. If something went wrong an Exception will be thrown that describe the nature of the error.

XKCDShortcode

This object has a render method that will be the function that renders HTML given the user’s input attributes. It will utilize the XKCDLoader object you will build to do the work of fetching the JSON for the XKCD number specified.

This object will also trap the Exceptions that the Loader might generate. Any errors it finds will be output to user instead of rendering the embed code.

XKCDShortcodePlugin

Finally this object will glue things together. Enable and disable methods will map to the WordPress API functions add_shortcode and remove_shortcode respectively. It will wire the add_shortcode callback to the XKCDShortcode object’s render method.

UML Design

Each of the objects discussed will correspond to PHP Classes. The Classes will also use other helper methods as needed. But from the point of view of interaction between these classes, the only public API methods they will use is the one discussed above.

Another reason to ignore the specifics of the rest of the implementation is to avoid Big Design Up Front. You don’t want to tie yourself down to a specific design just yet. As you will see later requirements tend to come up when you least expect them.

The exact details of the methods & properties of these Classes will be important once you start implementing them. Here’s the UML outline of this plugin.

You now have enough information to start coding! In the next part of this tutorial you will begin in earnest and implement the first piece of this plugin the XKCDLoader class.

Stay tuned for Part 2!

  • http://www.davidscanu.fr/ David Scanu

    Perfect tutorial I was looking for. I am starting plugin development and those four articles are gold !

    Do you use the plugin boilerplate on some projects ?