The Minimum Viable WordPress Plugin


It’s easy to think of plugins as big complex pieces of software that change WordPress in a huge number of ways. And many are. But for the sake of learning I think it’s useful to know what makes a plugin into a plugin, and what the minimum requirements for one are.

What’s a WordPress Plugin?

Concepts only here, so breathe easy.
4850586965_175427181c_o

A WordPress plugin is a small piece of PHP — the language that WordPress is written in — that extends or modifies WordPress in some way. In order to modify the core functioning of WordPress, (almost) all plugins need to use what is called a “WordPress hook”. We can think of WordPress hooks as literal hooks on which plugin’s leave notes for WordPress to come get them. If you need more explanation of that concept, I’d recommend my post from last week, called “A Simple Way to Understand WordPress Hooks“.

But beyond this functionality, WordPress plugins have a few other traits: they live in wp-content/plugins/ in your WordPress installation. They’re visible in your WordPress Dashboard if you click on “Plugins”. And they can be activated and deactivated — allowed to perform their task or do absolutely nothing — on that page.

The Completely Useless Do-Nothing Plugin

<?php
/*
Plugin Name: Name Of The Plugin
Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates
Description: A brief description of the Plugin.
Version: The Plugin's Version Number, e.g.: 1.0
Author: Name Of The Plugin Author
Author URI: http://URI_Of_The_Plugin_Author
License: A "Slug" license name e.g. GPL2
*/

This block above is taken from the WordPress codex, and essentially enables all the traits I described about plugin traits in the last paragraph: if you place this in a file which you name, for example, useless-plugin.php, and put it in your wp-content/plugins/ directory, you will get a plugin you can see in your WordPress dashboard’s Plugins page, and you’ll be able to Activate and Deactivate it.

Now if you know anything about PHP, you may be a bit confused. What people who know PHP will recognize is that everything between /* and */ is a multi-line comment, which is a fancy way to say it doesn’t do anything. From a perspective of pure (executable) PHP, you’ve just created an empty file. But this stuff is what WordPress uses to know the name of your plugin, the version of your plugin, the URL of your plugin, and everything else. So what we’ve done is tell WordPress all about our cool plugin, which does nothing. Rock!

A Minimal Functional Plugin — It Does Something!

<?php 
/*
Plugin Name: WordPress Hooks in Plain English example
*/

function wphipe_filter_example($title) {
	return 'Hooked: '.$title;
}
add_filter('the_title', 'wphipe_filter_example');

For the sake of brevity and clarity, I pared down the comment block we talked about in the last section. This is functional; even if you only include the name the plugin will show up in the dashboard. Never do it in your actual plugins — it will likely confuse both users and future developers — but it’s so much shorter, I’ve used it in this example.

The actual code here is from the introduction to WordPress hooks article I mentioned earlier. Because we’re striving for the shortest possible plugin, not the most useful one, this just adds “Hooked: ” to the front of your post and page titles. It’s not likely a feature that you want your plugin to have, but the basic logic of a PHP function — the function wphipe_filter_example($title) {} is the declaration of a function called wphipe_filter_example — which is hooked onto a preexisting part of WordPressing — in our example the_title — as its filter is widely applicable.

To expand your plugin, you can use many small functions that build together in complex ways to do awesome things. And you may use multiple WordPress hooks, or you may just need to use a single one that all your functions cascade out from. There are a wealth of possibilities when creating plugins, but trial and error is really the best way to learn what makes sense for your project.

Essential Tips for Making Good Plugins

We’ve covered the basics of what you need to make a minimum viable plugin, but that doesn’t exactly cover everything you need to know. So before we go a few things I think are vital to know:

  • You should almost always put your plugin in a folder. While both examples above work fine in the file useless-plugin.php in your plugins directory, there are lots of reasons that they should probably be in the wp-content/plugins/useless-plugin/useless-plugin.php. The biggest ones are that it makes it easy to include images, Javascript, or CSS files, break your PHP into pieces so you don’t end up with a massively too large file, and if you do decide to share you work in the WordPress Plugin Repository, you’ll have to anyway.
  • Your functions should always have a prefix. In our example above wphipe_ is our prefix. This is because given the way WordPress is structured, functions with names like change_title, which is reasonably clear but not very specific, can cause naming collisions with functions from other plugins, the theme, or core WordPress. PHP is, understandably, so confused about having more than one function that answers to the name change_title that it just stops working. So it’s best practice that every function you include in your plugin starts with a similar prefix unique to your plugin.
  • When a file only has PHP in it, omit the closing ?>. This is a bit rare, but good to know. Your primary function file should only have PHP in it — best not to include large block of HTML like you see in most theme page temples — and so will start with <?php and thus you may be tempted to end them with the matching ?>. But PHP is fine without it, and because if there are ever any empty lines after your ?> you’ll get complaints from PHP, it’s generally a better idea to not include it.

Have any questions about WordPress plugins and how to build up from the minimum viable version using best practices? I’ll be watching the comments, so ask away.

(Plugins illustration by Sean MacEntee)

About David Hayes

David likes learning, solving hard problems, and teaching. He bikes a lot, and lives in (and loves) Colorado. You can find him on Twitter as @davidbhayes and check out his latest hobby-project, Quodid, a monument to his love for pithy bits of wisdom.