on Writings, Tutorials, CMS, WordPress, PHP

Create bulletproof WordPress plugins that won't break your site

This tutorial will show you how to create WordPress plugins in a clean organized way to ensure they don't break your site, and are much easier to maintain. We'll do this by using a WordPress plugin boilerplate which will help us keep our code separate and clean.

In the past, you may have added functionality to WordPress by introducing snippets of code into your functions.php file. Adding functionality in this way can lead to conflicts in your code if you don't keep track of your naming conventions. This type of functional programming can also turn to spaghetti code pretty quickly, which is why a lot of developers prefer using an object oriented approach to development. It keeps your code encapsulated and prevents it affecting other plugins. If you want to write better, more maintainable plugins, I would advise using a boiler plate such as the one provided here. This tutorial will guide you through the plugin boiler plate in 5 parts.

1. Structural overview

For this tutorial, we'll be using the boiler-plate template I have created as a fork of Tom Mcfarlin's. I've removed a lot of files from the original to create a simplified version that beginners can more easily follow. It's also what I use to make quick plugins, and can be downloaded here. Let's start by looking at the file structure:

file structure

The top level folder is just called boilerplate. That’s what you drop into your WordPress plugin folder. The main file in here that we’ll look at is boilerplate.php.

Then we’ve got the public folder - inside this we have our main plugin class file, which includes all the code directly related to our plugin. All our functions sit inside this class, and because it’s within a class (not just dumped inside functions.php), we don’t have to worry about the names of our functions conflicting with that of any other plugins.

There are then 3 folders within the public folder: a css folder for all our plugin’s css, js folder for the javascript and a partials folder for any html views. All of which are registered from within the main class.

2.  How does WordPress find our plugin?

Inside, the first important file we will look at is boilerplate.php. Coincidentally, this is also the first important file WordPress looks at when your plugin is activated. When working with plugins, WordPress looks through all the directories in your site’s plugins folder, and within each plugin, the first file it looks at is the one with the same name as your folder. 

So in this case, it looks into the boilerplate folder and then at boilerpate.php. If you open this file, you’ll see that there’s actually a lot more comments than code.

It’s the place where you can provide a name and description to your plugin, currently it’s set to ‘Boiler Plate’, and the description: ‘ This is a short description of what the plugin does. It's displayed in the WordPress dashboard.’ If you were to change them, that’s what you’d see in admin dashboard plugin list.

3. I thought this was object oriented

The boilerplate.php file is just used for the above reason, and also primarily to include our main plugin class, which is sat in the public folder. This is done in just two lines of code: 

require plugin_dir_path( __FILE__ ) . 'public/class-boilerplate.php';

//load the plugin when activated
add_action( 'plugins_loaded', array( 'Boiler_Plate', 'get_instance' ) );

The first require line simply includes ‘class-boilerplate.php’ from the public folder. That’s the file where all our plugin logic will lie, encapsulated in its own class.

The second line, add_action hooks into WordPress’s plugins_loaded action hook. It’s what runs when our plugin is activated - we’re supplying it with an array consisting of our plugin class name (defined in class-boilerplate.php), and the name of the function from our class that we want to run, which in this case is get_instance.

4. Getting an instance of our class: class-boilerplate.php

Inside the public folder, class-boilerplate.php is our plugin’s main class. It’s the core of our plugin, and everything runs from within it. The name of the class is currently Boiler_Plate, matching the class we provided to the plugins_loaded action hook. So if you want to change the name of the class, make sure you change both occurrences of the name. 

The first function we will look at is get_instance, since that’s where we left off in the last step. When this function is called from boilerplate.php (when our plugin is activated) it simply returns an instance of the class. In doing so, a new object of this class is created, thereby triggering the class’s constructor method automatically.

5. Action hooks in the constructor

Now in the constructor of our class, we add our hooks into the WordPress actions our plugin wants to use. There’s a couple already there, and one custom action. The first two are as follows:

add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_styles' ) );  
add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_scripts' ) );

If you look further down our class, you’ll see two functions: enqueue_styles and enqueue_scripts - these are local to our class, and we want them to run when wordpress enqueues scripts for our site.

add_action() is the WordPress function that allows us to hook our own custom functions into WordPress actions. So we’re hooking our plugin’s two functions: enqueue_styles and enqueue_scripts into the WordPress wp_enqueue_scripts action. Then, when WordPress runs its own wp_enqueue_scripts() function with our plugin active, it also runs our two functions from our class.

What do these functions do? Let's start with enqueue_styles():

wp_enqueue_style( $this->plugin_name.'-public', plugin_dir_url( __FILE__ ) . 'css/public.css', array(), $this->version, 'all' );

It’s just one line, supplying a name for our css file, and the location of our css file. enqueue_scripts() does the same but for javascript.

That’s pretty much all there is to it - you can add hooks in the constructor, and define functions throughout the class. This is a great starting point for WordPress plugin development, however, if you would like an admin section for your plugin, I’d suggest getting a copy of the full version of the WordPress Boiler plate. Much of what you’ve read here will be transferrable, and you should be able to understand how the admin section works.