Designing a class to assemble plugin classes

Learning object-oriented programming with WordPress is a lot like embarking on an epic journey. You’ll experience some lows, some highs and some downright frustrating moments. But it’s all part of the learning process.

And, so far, we’ve done quite a bit of progress on our journey. We’ve looked at various WordPress problems. And we then solved them using a class or combination of classes.

We call this process “object-oriented design“. It’s been the focus of a lot of the articles on this site. Because of that, there’s a good chance that you’ve begun using it in your own projects. (And if you haven’t, you should try it!)

When that happens, you’ll start to notice that your project has a lot of classes. This tends to become a problem for a lot of developers. They wonder, “How do I assemble all these classes together!?” It’s not unusual for them to revert back to the standard WordPress way of doing things when that happens.

This is the problem that we’re going to explore in this article. We’ll look at how you can solve it using a dedicated class for it. To do this, we’ll start thinking about the job of the main plugin class.

Defining the plugin class

What do we mean by main plugin class? Well, let’s say we had a plugin namespace called MyPlugin. The main plugin class would be MyPlugin_Plugin. (The redundancy department of redundancy approves of this name.) Let’s work on defining what this class does.

Going back to the idea of aspect

If you created a class called MyPlugin_Plugin, what would you expect its role to be? This question highlights why it’s hard to create a “Plugin” class likeMyPlugin_Plugin. A class like that doesn’t have an obvious job.

This is a problem that we’ve encountered before. That time, we were struggling to define jobs for event listeners built around the plugin API. While the problem is different here, the approach to the solution is the same.

We have to go back to the idea of aspect. An aspect is a way to describe a more abstract type of job. This type of job also tends to touch more than one part of an application. We have to find what aspect of the application MyPlugin_Plugin is in charge of.

What aspect is it in charge of?

In this situation, the term “application” is a bit too wide and misleading. What you want to ask is “What aspect of the plugin is it in charge of?” We alluded to it earlier in the introduction.

We want the MyPlugin_Plugin class to be in charge of the assembly of the plugin. By assembly, we mean assembling our classes like we mentioned earlier. (That’s what we alluded to!) But it’s not limited to that either.

In practice, you need to do more than just assemble classes to assemble a plugin. You might also need to add routes to the router if you’re using a routing system. Or you might need to register event listeners if you’re using an event management system.

In the end, it’s about making sure that your plugin is ready to work once WordPress finishes loading it. To do that, MyPlugin_Plugin needs to touch different parts of the plugin. And that’s why the idea of aspect is useful here.

Dealing with the unknown

The way that we’ll design our plugin class is going to be a bit different from how we’ve done it in other articles. In normal circumstances, we’d be designing and coding everything around the class. But we won’t be doing this today since that would imply that we’d code an entire plugin. (And we’re not there quite yet!)

To deal with these unknowns, we’ll have to make some assumptions around our plugin. Otherwise, it’s a bit hard to design a plugin class when you don’t have a plugin! So let’s take a look at them. So what are our assumptions?

What classes exists already?

Let’s begin by looking at the assumptions made about the classes in our plugin. We spoke about the event management and routing systems earlier. We’ll assume that our plugin uses both of them.

We’ll also assume that our plugin uses a custom post type. And that we’ll need an event subscriber to register it. Our plugin will assemble that class as well.

As you can see, we’re starting to put together a few things that we’ve looked at in previous articles! Now, you don’t have to know how these components work for this article. We’re just looking to assemble them within our plugin class. This is as far as we’ll go this time.

But just in case you missed them earlier, here are the links to the three components used in this article:

Using an autoloader

The second assumption that we’re going to make is that our plugin uses an autoloader. It’s an important tool for organizing your files in an object-oriented plugin. It lets PHP require class files as they’re needed as opposed to having us do it ourselves.

We call that process autoloading. An autoloader is a special class in charge of that. With it, we won’t have to worry about requiring class files for our plugin to work. That’s why we’ll assume that there’s one.

Plugin files and directory structure

Let’s continue on the theme of file organization. We’re going to look the directory structure of our plugin and the assumptions that we have about it. Here’s what we expect within the context of our example.

Our directory structure follows the standards from PHP-FIG. The src directory acts as the root for all the plugin code. And, except for myplugin.php, each file will only contain a single class.

With that in mind, all the files above are for classes that will show up in our example. The content of the files isn’t important for this article. If you want to know more about the code in them, you can always refer to the articles linked earlier. For now, we’ll just describe the ones that we’ll focus on a bit more for this article.

Plugin.php

We’ve been speaking a lot about the MyPlugin_Plugin class. Plugin.php is the file where the code for the class will reside. It’s the main focus of this article.

Autoloader.php

Autoloader.php is the file that contains the code for MyPlugin_Autoloader. This is the PSR autoloader that our plugin depends on. If you want to see what the code for it, you can refer to this example.

myplugin.php

myplugin.php is the file that WordPress will use to load our plugin. This is where the code to setup our MyPlugin_Autoloader class should be. It’s also where we’ll do the initial call to our MyPlugin_Plugin class. (This is something that we’ll go over later.) The name of the file follows the WordPress plugin development best practices.

Laying the foundation of our plugin class

So that covers the unknowns around our plugin! We’ve also defined what our MyPlugin_Plugin class does. Now, it’s time to start building it!

First, we need to lay some foundation. Above is the empty MyPlugin_Plugin class that this article will focus on. Like we mentioned earlier, you’ll find the code for it in Plugin.php in the src/MyPlugin/ directory.

The code above is the initial setup the myplugin.php file at the root of our plugin directory. We start off by adding the plugin file header so that WordPress recognizes the plugin. We only put Plugin Name because it’s the only one that’s mandatory.

Below is the code to setup our plugin autoloader. Because an autoloader can’t autoload itself (that’d be trippy!), we have to do it ourselves by requiring the file. We then call the register static method to register our autoloader with PHP.

Constructor

We’ve already done enough work to make a first pass at the MyPlugin_Plugin constructor. Everything inside the constructor ties to the assumptions that we laid out earlier. It initializes the two systems that we said were part of the plugin.

We mentioned that there was an event management system. MyPlugin_EventManagement_EventManager is the class in charge of that. Meanwhile, MyPlugin_Routing_Router is in charge of the routing system.

Why do we create these objects now? It’s because we only want one instance of each of these systems for our plugin. And what better place to store them than in our MyPlugin_Plugin class!

Why not use singletons?

We’re going to do a small tangent to discuss the use of singletons here. But first, what’s a singleton? A singleton is a type of class that only allows for a single instantiated object of itself to exist at all times.

This need for MyPlugin_Plugin to assemble all these classes puts a lot of pressure on us to use it. After all, we only want one instance of MyPlugin_EventManagement_EventManager and MyPlugin_Routing_Router. So why not just force all these classes to be singletons? Because it’s addicting and goes against the nature of object-oriented programming. (If everything is a singleton, why even use object-oriented programming?)

Now, this doesn’t mean that singletons are evil. They have their uses in object-oriented programming. It’s just not here in the context of WordPress.

A question of trust

It all comes down to trust. You should trust your fellow developers with your code. The reality is that it doesn’t matter if someone creates a second MyPlugin_Plugin object.

Sure, we’ll have a second instance of both the event management and routing systems. But this won’t break anything. And, if it does, that’s ok. It’s not your responsibility to prevent them from trying it. (You should leave them the freedom to experiment.)

Instead, we should focus our energy on designing a meaningful MyPlugin_Plugin class. One that solves the set of problems that we identified earlier. Not this problem of trust which you shouldn’t see as a problem to begin with.

Initializing our plugin class

Alright, with this out of the way, we can proceed with our MyPlugin_Plugin class! We’ve defined a constructor for it, but we still haven’t initialized it anywhere. We can do this in the myplugin.php file by creating a new MyPlugin_Plugin object. You can see how below.

Moving on to the design of our plugin class

Now that we’ve laid some good groundwork for our MyPlugin_Plugin class. It’s time to start going over the design of the class. There are some interactions between WordPress and the class that can cause problems. We’ll analyze them and discuss how we solved them in our class.

Loading our plugin

Our first design challenge is how to load our plugin. What does loading mean in this context? Well, it’s not autoloading! We took care of that earlier in myplugin.php.

No, this is something different. We’re coming back to this idea of assembling our plugin. We’re going to focus on what our plugin needs to do during WordPress loading process. What outcome are we looking for when WordPress finishes loading?

Well right now the plugin doesn’t do anything, so we need to get it to work! (Duh!) But what does that imply? It implies that whatever we didn’t assemble in the constructor needs to be at that point. Based on our assumptions, let’s look at what we haven’t assembled yet.

Event subscribers

While we already initialized the MyPlugin_EventManagement_EventManager class, we didn’t assign it any event subscribers. Without these, our plugin can’t interact with WordPress using the plugin API. Since our MyPlugin_EventManagement_EventManager class comes with an add_subscriber method, we can use it to add event subscribers.

Above is our modified constructor. We added a call to the add_subscriber method which registers the MyPlugin_Subscriber_CustomPostTypeSubscriber class. This is an event subscriber in charge of registering the custom post type used by our plugin.

Now, the way we just did this is a bit sloppy. A plugin can have dozens of event subscribers! We should find a cleaner way to add them without adding dozens of add_subscriber calls.

Above is a cleaner way to handle this. Instead of dozens of add_subscriber calls, we have one inside a for loop. The loop goes through all the event subscribers returned by the get_subscribers method.

The get_subscribers method is just a way for us to group all our event subscribers. You don’t have to do it this way if you prefer not to. But you should try to keep the constructor clean and that’s one way to do it.

Routes

Next up is the routing system. Like the event management before it, we only initialized one part of the routing system. That’s the MyPlugin_Routing_Router class. We still need to register routes using the add_route method.

So we’ve gone ahead and done the same thing that we did with the event subscribers. We have a get_routes method that’ll return all our plugin routes. We then pass them all into the router using add_route.

Making it work with the plugin API

An important component of building plugins is the plugin API. After all, that’s why we have an event management system! And we’ve been putting it to use by connecting event subscribers to WordPress events.

But while we’ve done good work on that front, we haven’t returned the favor to other developers. We haven’t given them a way to connect to us so that they can change the behaviour of our plugin class. This is what we’ll tackle next.

Adding connection points

So where should we add these connection points? The two obvious ones are in our get_routes and get_subscribers method. This would let other developers add their own routes and event subscribers to our plugin.

As you can see, we’ve changed both our get_routes and get_subscribers method. They don’t just return their arrays anymore. Instead, we pass them to our event manager’s filter method. Whatever the filter method returns is what gets sent back to the constructor.

Just in case, here’s a small refresher on the filter method. In the event management system, it’s the method that calls the apply_filters function. This is what will let other developers change our routes and event subscribers.

A problem with our timing

While our get_routes and get_subscribers method work as they should, our work isn’t done here. There’s still a problem that we haven’t addressed. That’s the timing of the call to the filter method.

Right now, it happens at a random time. That’s because we’ve tied it to when WordPress loads our plugin. The issue with that is that WordPress doesn’t load plugins in the same order. It varies from site to site and plugin authors can also change it.

This means that our changes to get_routes and get_subscribers are inconsistent. If someone’s plugin loads before ours, they can change our routes and event subscribers. But if their plugin loads after ours, they can’t. We’ve already called the filter method in our get_routes and get_subscribers methods.

Delaying the loading of our plugin

A solution to this problem is to delay when we’re going to call our timing sensitive methods. Instead of doing it in the constructor, we do it at a later time. That way, we can be sure that every plugin has had a chance to load.

The first thing to do is move these two methods out of the constructor. That’s the job of the load method shown above. It’s where we’ll put these timing sensitive method calls.

Now that we’ve moved our method calls to the load method, we need to ensure it gets called at the right time. We’ll do this by registering the load method with a WordPress hook. Which one should we use?

The one that makes the most sense is wp_loaded. It’s the last hook that WordPress calls during its loading process. Unlike the plugins_loaded hook, this one also lets themes make changes to our plugin.

The last thing we need to do is register our load method with the wp_loaded hook. To do this, we need to make a small change to our myplugin.php file (shown above). We added a call to the add_action after we initialized our MyPlugin_Plugin object.

Letting your plugin load only once

As things stand, a developer can call our load method more than once. It’s possible that you’re uncomfortable with that idea. Let’s look how we can prevent our load from running again after it’s run for the first time.

We added a loaded variable to our MyPlugin_Plugin class. We’re going to set it to false in the MyPlugin_Plugin constructor. This way we ensure that it always starts as false.

We then use the loaded variable in our load method. We gate the beginning of the method by checking if loaded is true. If it is, we exit the method right away.

If it’s still false, we proceed and run the code in the load method. Once it gets to the end, it sets loaded to true. This is what will prevent it from running again if someone calls it again.

Dealing with directory sensitive WordPress functions

We spoke earlier about the directory structure and where we put our plugin files. This decision to organize our plugin this way doesn’t come for free. There’s a repercussion to it that we haven’t discussed yet.

In some cases, WordPress relies on files being in the root directory of their plugin directory. Certain functions like plugin_basename expect our files to be there by default. That’s because they expect you to pass the __FILE__ predefined constant to them.

But we only have one file in the root of our plugin directory. It’s myplugin.php. So how can we use this fact to pass this information to our plugin?

An easy solution is to pass __FILE__ to our MyPlugin_Plugin constructor. This is what we did in the myplugin.php file above. Doing this gives our plugin the opportunity to use the WordPress functions that need it.

The only thing left is to update the MyPlugin_Plugin constructor. Our constructor now has a file parameter. We pass it to the plugin_basename function to get the base name of our plugin. We then assign that value to the basename variable that we added to the class.

Overall, this is a good solution to the problem. The MyPlugin_Plugin class is the natural location for this information to reside in. After all, it should be the one in charge of knowing about its own basename.

The next phase of our journey

And with this, we’re going to wrap up our look at our MyPlugin_Plugin class! You can find all the complete code for it here. Feel free to refer to it as needed!

Now, from a design perspective, this class wasn’t too complicated. But it’s still possible that you found this a bit overwhelming to understand. That’s ok!

You shouldn’t feel ashamed about feeling this way. We’re trying to combine a lot of moving pieces. It’s normal if your head spins a bit thinking about it. This is where most of the complexity comes from after all.

That said, this is an important moment in our journey. We can’t keep looking at problems in isolation forever. We need to start looking at the big picture. That’s why we started piecing all these different solutions together.

Photo credit: Alden Jewell

  • I know the singleton is almost always bad, but I still think that the main plugin class is a great use for it. Lets say I’m instantiating a bunch of other classes from inside of my main plugin class, and I might need those objects later. Having one singleton for the main class avoids having to use lots of other singletons later.

    • I agree THIS is the place where it’s the most justifiable. And I understand why it makes sense. (You should use if you want to!)

      I’m just trying to promote alternatives because it’s easy to go down the rabbit hole. (Oh I just need one of or one of that) I have a followup article I want to do where I want to cover an alternative way to handle single instances. That said, it wouldn’t solve the plugin class singleton issue (I think)

  • Nice article, a minor point but IMO I wouldn’t put anything under a src folder as far as PHP is concerned. If you have an application where you have source and binary files then having a src folder makes sense. However as the PHP script is the src I think this just makes your folder hierarchy(and possibly your namespace hierarchy if your namespace hierarchy follows your folder hierarchy) deeper with little or no benefit.

    • I agree. The reason I use it is because I found it useful was because I want other folders as well like ‘assets’. You could also do a separate ‘tests’ folder as well. What would you suggest instead of ‘src’?

  • So my first thoughts would be to have a structure similar to that below.

    myplugin/
    |
    | |– Includes/(for those files which are used directly bu the plugin e.g. class files)
    | | |– class-my-core-functions.php
    | | |– Autoloader.php
    | | |– Plugin.php
    | |– EventManagement/
    | | |–EventManager.php
    | | |–SubscriberInterface.php
    | |– Routing/
    | | |– Route.php
    | | |– Router.php
    | |– Subscriber/
    | | |- CustomPostTypeSubscriber.php
    | |– Assets/
    | |– CSS/
    | |– JS/
    | |– Views/
    | | |–settings-partial-1.php
    | | |–settings-partial-2.php
    | |– Tests/
    |–myplugin.php

    But that got me thinking, does this make it clear what should go where. If not then why do it? So I think maybe something more like the following would work better

    myplugin/
    |
    | |– Classes/(single class files used by the plugin – although I’m not overly happy with calling it classes)
    | | |– class-my-core-functions.php
    | | |– Autoloader.php
    | | |– Plugin.php
    | |– Libraries (a grouping of php scripts which logically fit together and can be used across multiple projects)
    | | |– EventManagement/
    | | | |–EventManager.php
    | | | |–SubscriberInterface.php
    | | |– Routing/
    | | | |– Route.php
    | | | |– Router.php
    | | |– Subscriber/
    | | | |- CustomPostTypeSubscriber.php
    | |– Assets/(images and fonts)
    | |– Presentation/ (assets which are used in the presentation of plugin screens)
    | | |– CSS/
    | | |– JS/
    | | |– Views/
    | | | |–settings-partial-1.php
    | | | |–settings-partial-2.php
    | |– Tests/
    | |– Vendor/ (any third paty libraries)
    | | |– log4php
    |–myplugin.php

    Not that i use this structure at the moment, but think I might well do going forward. I do not like putting too many scripts in the top level folder. Typically I will use the main WordPress plugin file to bootstrap the rest of the plugin and take an OO approach to building the functionality of the plugin.

    Being a bit of an old patterns freak I do like to keep my html out of my functions :-).

    PS sorry if the indentation of the folder structure doesn’t work too well in ASCII.

    • It’s all good! And yeah, I haven’t settled on something I like that much yet. I used ‘src’ because it’s pretty standard in PHP projects. But, like you pointed out, it might not be ideal either.

      The way you break out assets is pretty much how I see it. 🙂

      • I have seen JS and CSS files put in the assets folder but to me this doesn’t seem right because I see JS and CSS as code as much as the PHP, although this may be a contentious point of view.

  • Great article. I like how you control the plugin’s load time which is delayed. I am using the hook ‘plugins_loaded’ for my plugins where I run the mandatory methods for loading dependencies, creating cpts and similar. I even add my own action hooks which work similar to ‘init’ so that I can easily extend my main plugin with other plugins but also be sure that my main plugin has run already.

    I found out that the singleton pattern is useful for the main plugin’s class which can store steps or even some parameters that could be useful for the whole page life cycle. For example: I have been creating a simple advertising plugin for a tutorial of mine where I use the same instance of my main class in the ‘init’ hook to get the ads and then use that data to show the ads in header and in footer (if there is any of course).

    That data is also then useful to decide if I the scripts/styles have to be enqueued or not.

    • The big thing with ‘plugins_loaded’ is that it happens before themes get loaded. So if someone wants to make changes in a theme vs a plugin, they can’t. That’s why I use ‘wp_loaded’.

      Josh Pollock thinks singletons make sense here too. I think it’s the only place where it kinda makes sense. But, to me, it feels unnecessary to force that pattern when there’s no need to.

      Otherwise, glad you found it useful and that you’re doing something similar! 😀

  • Manzurul Haque

    No doubt this is a great article. But for plugin development it is possible to use more like MVC framework. I have found one ‘herbert plugin framework’ which looks great to me.