Speed up Development Using the WordPress Plugin Boilerplate
A low learning curve into WordPress plugin development means that there is no one definitive way to build a plugin. A plugin can be as simple as a single file like Hello Dolly, or it can be structured as complex as needed to cater for various requirements and functionality. The WordPress Plugin Boilerplate aims to provide a standardized, high quality foundation to build your next awesome plugin.
In this first part of the series, we’ll take a deep look into the boilerplate, including how the files and folders are structured as well as code organization of the boilerplate.
WordPress plugin boilerplate is originally an initiative by Tom McFarlin to provide a standardized, object-oriented approach to building WordPress plugins. Since the boilerplate is built on top of the Plugin API, and following the Coding Standards and Documentation Standards recommended by WordPress, you can be sure that you’re in safe hands.
Recent update of the boilerplate to version 3.0.0 brings major improvements to the boilerplate itself, in terms of code organisation, as well as further separation of concerns within your plugin. If you’re already familiar developing your plugin using the previous version of boilerplate (v2.6.2), you might need to take some time to relearn what’s new in the latest version, which includes new folder structure.
This boilerplate is no longer maintained by Tom McFarlin himself (at the time of writing), he’s passed the torch to Devin Vinson. The development is still continuing as usual, so if you have any issues, feel free to report one at the GitHub repository. Contributions are also definitely welcomed.
Getting Yourself a Copy
The simplest way to get a copy of WordPress plugin boilerplate is by cloning the git repository itself.
git clone https://github.com/DevinVinson/WordPress-Plugin-Boilerplate.git
Or you can always download a zip copy from the GitHub repository.
Since version 3.0.0 was released, the plugin cannot be simply copied into your
wp-content/plugins directly. This is because the actual source code of the plugin is not contained in the root directory, but actually resides in the subdirectory called
trunk. Don’t worry about this now, we’ll talk about the new folder structure later on in this article.
Full detailed instructions on how to install the boilerplate correctly is described in the
README.md file. In a nutshell, you can either:
- Copy the
trunkdirectory into the
- Copy the whole boilerplate directory, and then create a symbolic link for the
trunksubdirectory to the
wp-content/plugins/<plugin-name>/. Creating the symbolic link will depends on the operating system that you’re using.
Once you’ve done that, you should now find a plugin called
WordPress Plugin Boilerplate in your plugin list in the admin dashboard, assuming you haven’t made any modifications to the boilerplate itself. Simply activate the plugin and you’re good to go!
Using the Online Generator to Customize the Plugin
Once activated, you’ll have a sort of vanilla plugin that doesn’t really do anything – that is, just yet. You’ll also need to run a search and replace to the whole boilerplate’s codebase, and this process can be very tedious and time consuming. Luckily, there is an unofficial generator built by Enrique Chavez that can automate the process. Simply head to http://wppb.me/ and complete the form located at the bottom of the page to generate a personalized copy of WordPress plugin boilerplate.
Let’s take a closer look on how the WordPress plugin boilerplate version 3.0.0 is organised compared to the old one. As mentioned previously, the actual plugin code is contained in a subdirectory called
trunk instead of in the root directory.
This is to follow the standards employed in the WordPress official plugin repository which contains three main directories which are
trunk. The boilerplate already provides two of those,
Here’s a complete directory and files contained in the boilerplate, at the time of writing:
|-- plugin-name/ | |-- assets/ | | |-- banner-772x250.png | | |-- icon-256x256.png | | |-- screenshot-1.png | | | |-- trunk/ | |-- admin/ | | |-- css/ | | | |-- plugin-name-admin.css | | |-- js/ | | | |-- plugin-name-admin.js | | |-- partials/ | | | |-- plugin-name-admin-display.php | | | | | |-- class-plugin-name-admin.php | | |-- index.php | | | |-- includes/ | | |-- class-plugin-name-activator.php | | |-- class-plugin-name-deactivator.php | | |-- class-plugin-name-i18n.php | | |-- class-plugin-name-loader.php | | |-- class-plugin-name.php | | |-- index.php | | | |-- languages/ | | |-- plugin-name.pot | | | |-- public/ | | |-- css/ | | | |-- plugin-name-public.css | | |-- js/ | | | |-- plugin-name-public.js | | |-- partials/ | | | |-- plugin-name-public-display.php | | | | | |-- class-plugin-name-public.php | | |-- index.php | | | |-- LICENSE.txt | |-- README.txt | |-- index.php | |-- plugin-name.php | |-- uninstall.php | |-- .gitignore |-- CHANGELOG.md |-- README.md
Here’s a little explanation of what each file and folder does:
Provides a sane default .gitignore to most of the stuff that should not exist in your git repository.
Standard changelog of changes to the boilerplate with date of change.
A useful starting guide that lists the installation instructions, among other few other sections such as tools recommendations and credits.
This directory contains the recommended resources that you need to provide whenever you decide to publish your plugin to the WordPress plugin repository. All of the images contained in this directory is the recommended resolution for publishing.
This is the actual plugin that you are going to develop. There are a few folders that separate the codebase between admin and public facing functionality. We’ll go through in details of what each subdirectory represents.
There are three directories contained within the
partials. As its name suggests, all admin facing functionality should be placed here. By default, the
plugin-name-admin.cssis enqueued to your
class-plugin-name-admin.phpwill provide generic functionality where you can define your admin specific hooks.
This directory is pretty much similar to what the
admindirectory has to offer, the only difference is that the
publicdirectory should be used to store all of your public facing functionality codebase.
.potfile where you can provide translation functionality with your plugin.
This is probably where pretty much all the magic happens. There are five starting classes included by default, which we will discuss later in the next section.
A copy of GPL v2 license is included by default.
A starting point for your plugin README file. This file pretty covers all of the sections that you can further fill in to provide a good plugin page on WordPress plugin repository.
The point of entry for your plugin. In here, a general plugin file header is included that you can modify to your own liking. The
register_deactivation_hookare also registered in this file if you ever need to include some sort of functionality on plugin activation and/or deactivation.
As mentioned before, there are five default classes provided inside the
trunk/includes directory. Let’s see what each of these do:
This class is instantiated during the plugin activation. It only has one static method,
activate()which is registered to the
register_activation_hook. Use this class whenever you find yourself in need to do something on plugin activation such as creating custom tables or saving default options.
The counterpart for
class-plugin-name-deactivator.php. It also only contains one static method,
deactivate()which can be used to run any functionality during plugin deactivation.
A starting point for i18n functionality of your plugin. It has one property,
$domainwhich stores your plugin text domain. This property can be set using the public method
set_domain(). Finally, the method
load_plugin_textdomain()in this class will be called whenever the plugin is loaded.
Probably the most important class in the boilerplate. It contains two properties,
$filterswhere all the hooks registered in the plugin will be stored. It provides two simple wrapper functions,
add_filterthat are used to add actions or filters into the
$filtersproperties. This should not be confused with the WordPress default
add_filter()function as this class does not actually register them directly. All of the hooks will only be registered during another method called
The class that glues all the pieces together. It holds important information about the plugin such as the plugin name and version. Plus, it will load the dependencies using the method
load_dependencies()which will include all the above four classes and plugin text domain will be set using
set_locale()method. All admin and public hooks that were previously registered can also be defined here.
This class also provides simple
getmethods, such as
get_plugin_name()to return the plugin name,
get_version()to return the current plugin version and
get_loader()that keeps an instance of
In short, the WordPress plugin boilerplate provides a terrific starting point for plugin developers. It follows the recommended WordPress coding standards as well as WordPress documentation standards so you know you’re starting off on the right foot. Besides, publishing to the WordPress plugin repository is made easier since the boilerplate already provides much of what you’ll need.
Once we’re familiar with the code organisation and folder structure, we’ll explore how to develop an actual plugin using the WordPress plugin boilerplate in the second part of the series.