Writing WordPress plugins is great fun because you can build awesome stuff and share it with tons of people very easily. Getting started can be frustrating because there are so many different ways to organize your code and it’s hard to know what’s best for your project. In the next few posts, I’ll share some of the tips I use to code WordPress plugins so they are easy to understand and maintain.
ChordWP The Example Plugin
For the next few posts, we’ll be exploring some ideas and good practices for writing your own WordPress plugins. Everybody’s always learning and I’m certainly no exception to that rule. So, if you’ve got some tips or ideas on how to do things better, please share your tips in the comments.
To illustrate the points, I’ll be referencing a plugin I wrote called ChordWP which lets you share sheet music with WordPress. The general idea behind this plugin is that you can write music in the WordPress editor that, when presented to your readers, looks nice. We’ll use this plugin to cover things like:
- Object oriented programming for WordPress plugins
- Organizing your files
- Using filters so other people can build on top of your plugin
- Automated testing for your plugin
You may want to download ChordWP so you can follow along, seeing full examples of the code we are going to be talking about.
The Main Plugin File
The first file that gets loaded is the file that generally has the same name as your plugin and lives in the root of your plugin directory structure. You need to make sure this file has a very specific name because it needs to be unique across all the other plugins used on the WordPress site. Naming the file is the easy part. The harder part is figuring out how to structure the code in the file. Even though WordPress core is an event driven architecture, it’s probably a good idea to write your plugin in an object oriented way. This is helpful for at least three reasons:
- It contributes to building a well organized structure for your plugin code
- It helps isolate your plugins functionality without having to use ridiculously long function names
- It helps WordPress prevent loading your plugin multiple times during a request cycle
If the plugin you are working on is really small, then you can get away with less structure and organization in your code. The bigger your plugin gets, the more you will benefit from a well organized, object oriented code base.
Making Sure Your Plugin Only Loads Once
Using classes to organize your plugin code gives us a great way to make sure WordPress only loads your plugin one time during the life cycle of the request. The key to getting this to work is checking to see if the `class_exists` before running the code that sets up your plugin.
if ( ! class_exists('ChordWP') ) {
// Code to initialize and start up your plugin
}
Once we define the `ChordWP` class, then the call to `class_exists` will return `true` and all the code contained in the conditional block will get skipped over. That will ensure that we only load our main class one time.
The Singleton Pattern
This is a fancy term for writing a class that only allows one instance of itself to be constructed. Subsequent calls to construct a new instance of the class simply returns the instance that it created the first time. In other words, it’s a way to code up a class so that no matter how many times you try to create new instances of it, you are always just working with a single instance. This provides two ways of insuring that our initialization code only gets run one time:
- Loading: If your plugins main class is already loaded, the `class_exists` check will prevent WordPress from loading your class again. This saves us from the dreaded error message saying the class has already been defined.
- Calling: If you call your plugin’s main class from somewhere else in you code, or another developer tries to make use of your code, the singleton pattern makes sure your plugin is initialized only one time.
instance() vs __construct()
Notice that in the main ChordWP class we have both `instance()` and `__construct()` methods. Since the main ChordWP class is a singleton, we never actually call `__construct()` directly. The ChordWP class has a protected static member variable called `$instance` that holds an instance of our class. So, rather than calling `__construct()` like you would on a normal class, you call `ChordWP::instance()` instead. If the `$instance` variable hasn’t been set yet, ChordWP will call `__construct()` on itself to create the first and only instance of this class. All subsequent calls to `ChordWP::instance()` simply return a reference to the instance that was created.
Bottom line: Always call `ChordWP::instance()` never call `new ChordWP()`
The Kickoff
Simply defining you plugin’s main class doesn’t actually run anything. You need to actually call the `ChordWP::instance()` method we defined in our Singleton class. The very last line of our main plugin file is actually outside of the `ChordWP` class, but still inside the `class_exists` conditional block. It wouldn’t hurt anything if we put `ChordWP::intance()` outside of the `class_exists` if block since ChordWP will only construct itself once. But, too keep things as clean as we can, you only need to kick things off one time and you should do that right after you define you main class.
Summary
We discussed one way of organizing the code your primary plugin file in an object oriented way using the singleton pattern. This makes sure your class only gets loaded one time and provides a clean foundation for developing the rest of your plugin.
To see all the code you can download the ChordWP plugin here and checkout the `chordwp.php` file.
