- Making Remote Requests
- Generating HTML
- Connecting to WordPress’s Shortcode API
- 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
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
The plugin embeds a specific numbered XKCD comic into a
Post using the shortcode syntax
[xkcd]. The image is embedded along with it’s
title text. Here’s what the finished version looks like,
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
is loaded from the XKCD.com using it’s JSON API.
A Few Things You Will Need To Know
JSON from the XKCD servers you will use
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.
wp_remote_retrieve_body goes hand in hand with
extracts out the response body text received from the xkcd.com server.
You will use
json_decode to convert the response returned from the server
into a native PHP object that is simpler to work with.
Finally for the WordPress integration you need the
add_shortcode function to register the
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 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,
XKCDShortCodePlugin. Here’s an overview
of what these objects would do.
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.
This object has a
render method that will be the function that renders HTML given
the user’s input attributes. It will utilize the
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.
Finally this object will glue things together.
disable methods will
map to the WordPress API functions
It will wire the
add_shortcode callback to the
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
Stay tuned for Part 2!