One of the great things about WordPress plugins is that it’s fairly easy to get started and build something functional without a ton of effort. However, once you get beyond a simple concept, have to maintain a growing codebase, or find yourself repeating similar steps, structure becomes essential.

A recent discussion on Post Status and some nudging from Nate Wright convinced me to write a bit about my approach to building plugins.

In most cases, I prefer to build standalone plugins that don’t rely on external libraries if possible due to the lack of dependency management in WordPress (projects where Composer is available is another story). I value simplicity and the ability to re-use code despite my tendency to over-engineer and abstract more than is always necessary.

Autoloading

Autoloading classes allows your code to be loaded automatically when it’s needed instead of having to litter your code with a bunch of calls to include() and require(). Basically, when PHP encounters a class it doesn’t know about, it runs through a list of registered autoloaders until it finds one that knows how to load it.

An autoloader is just a callback function, similar to a WordPress filter, that takes a class name and requires the path to the file where the class is defined. As you can probably tell, using an autoloader means you need to follow a particular convention when naming files. It’s also beneficial to only define a single class in each file and nothing else.

WordPress has its own naming conventions for files with classes, but it can become a bit unwieldy with longer file names. I usually follow PSR-0 for distributed plugins or PSR-4 for internal code, but writing an autoloader using the WordPress convention is trivial.

I usually put PHP classes in a /classes or /php directory, but some developers put them in /includes or /src.

Bootstrapping a Plugin

With all that out of the way, I usually start most plugins with just two classes I can copy between projects to provide a bit of structure:

• AbstractPlugin.php – A base plugin class that can be used to register hooks and access plugin information from other classes.
• AbstractProvider.php – A base for classes that register actions and filters to extend and automatically gain a reference to the main plugin instance.

Each plugin has a main class that extends AbstractPlugin.php and should be instantiated in the main plugin file. The main class may have a few methods that help set up the plugin — sometimes it might not have anything. Instantiating it looks like this:

This works similar to a singleton or a static factory method, but moves the responsibility out of the class itself, making the class easier to test, and provides a more simplistic API.

Calling the loader function in internal classes should be avoided in favor of injecting the plugin object where it’s needed. The loader function is mainly for other plugins, helper functions, or templates that need access to the main plugin instance.

Hook Providers

It’s nearly impossible to develop a WordPress plugin that doesn’t use actions and filters. Without some guidelines, it can be difficult to know where and when to register them, especially if they require interacting with other hooks later in the page life cycle.

Personally, I prefer to register the hooks in the same class where the callbacks are defined to keep the code self-contained and make it easier to understand. That being said, please don’t register hooks in the constructor.

I group the various hooks needed to implement a feature in a single class and register them in a method called register_hooks(). Generically, I refer to these types of classes as “Hook Providers.” You’ll often see plugins do something similar in a method named run(), init(), or setup().

In the past I would instantiate these classes in a method and then call the run() method manually like this:

Sometimes you’ll see classes loaded like that in the same file where they’re defined. That always felt dirty and gets ugly pretty quickly. It requires the parent class to know about all the classes it’s instantiating and causes the registration methods to be spread out among various files.

Instead, hook provider classes can extend AbstractProvider.php, which helps clean the code up a bit and allows all the providers to be instantiated in the main plugin file.

Given the plugin loader function from earlier, registering hook providers works like this:

Registering hook providers this way automatically calls their register_hooks() method and injects a reference to the main plugin class for any WordPress API methods that need a reference to the plugin’s path, URL, slug, etc. It’s also possible to inject dependencies when instantiating the hook providers, or the main plugin instance can be used as a service locator if that’s your thing.

General Recommendations

That’s my general approach to starting a new plugin and it’ll likely evolve over time, especially as WordPress’ minimum PHP requirements are increased. It’s not meant to be dogmatic, but if you’re struggling with structure or spending too much time scaffolding new plugins, give it a shot and see what you think.

No matter your approach, here are some things I do recommend:

• Define the main plugin class in its own file (not in the main plugin file).
• Don’t register hooks in constructors.
• Don’t execute code in the same file where functions or classes are defined.

A bare bones example can be found here:

Further Reading

To see a functioning plugin using this approach, take a look at the AudioTheme Agent.

John P. Bloch open-sourced his approach to building plugins last year and it really resonated with me and served as the base for the AbstractPlugin class. His library, along with the idea of “root composition” as espoused by Tom J. Nowell, have been foundational to the way I’ve been building plugins since. John James Jacoby’s SLASH Architecture also provided a great deal of inspiration, so I’d recommend checking out those resources if you want to dig deeper.