Intro to WordPress Plugin Development: Best Practices

In this first part of the Intro to WordPress Plugin Development series, we’ll be taking a look at some best practices for coding your plugin. Specifically, we will take a look at these areas:

• How to set up the plugin header
• Formatting your code
• Use of meaningful names in files and code
• File organization

How to set up your plugin’s header

The main file in your plugin must have a properly formatted header. If it doesn’t, WordPress won’t be able to display the correct information on the site the plugin is installed on.

At the absolute minimum, the plugin’s header must have the plugin name, but additional information can (and probably should) be added.

Here is an example from the plugin: Tabbed Account Area for Easy Digital Downloads.

<?php
/*
Plugin Name: Tabbed Account Area for Easy Digital Downloads
Description: Creates tabbed content for your account area on Easy Digital Downloads
Plugin URI: https://scottdeluzio.com
Author: Scott DeLuzio
Author URI: https://scottdeluzio.com
Version: 1.0.3
Text Domain: tabbed-account-area
*/

While the plugin won’t do much at this point, a PHP file with just the information above would be considered a valid plugin. It would show up in the list of plugins on your WordPress site, and it could be activated, deactivated, and deleted.

Formatting your code

Properly formatting your code is really important. When I first started coding, I didn’t realize how important it was until I had to go back and look at something I had done 6 months earlier and realized how poorly formatted my plugin was.

Indentation

It is important to indent the lines in your plugin so that it is easy to read.

For example, here is a function with no indentation:

<?php
function taa_account_area_hidden_content( $atts, $content = null ) {
if ( !is_user_logged_in() ) {
return false;
} else {
return do_shortcode( $content );
}
}

Here is the same function with indentation:

<?php
function taa_account_area_hidden_content( $atts, $content = null ) {
	if ( !is_user_logged_in() ) {
		return false;
	} else {
		return do_shortcode( $content );
	}
}

This one is easier to read because of the indentation.

Spacing

When writing code, it is easy to get into the habit of not adding spaces to the code. This forces all of the code to be squished together, and like the indentation example, makes it harder to read.

Here is that same function from earlier with no spacing:

<?php
function taa_account_area_hidden_content($atts,$content=null) {
	if(!is_user_logged_in()){
		return false;
	}else{
		return do_shortcode($content);
	}
}

While the two functions would behave exactly the same way, this one would be more difficult to read.

Also, when creating variables, or an array, developers frequently add a single space after the variable or key name. This makes it difficult to read through a group of similar items.

<?php
    $name = 'Joe Smith';
    $address = '123 Main St';
    $city = 'Anytown';
    $phone_number = '555-555-5555';
    $email = 'joe.smith@example.com';

All of that is perfectly valid code, but it isn’t really easy to read. Let’s try again with a little better spacing.

<?php
    $name         = 'Joe Smith';
    $address      = '123 Main St';
    $city         = 'Anytown';
    $phone_number = '555-555-5555';
    $email        = 'joe.smith@example.com';

Sort of like a table, all of the variable names are spaced to the left, and their values are to the right. The = sign is in the same spot on each line.

The same principle would apply to other code like arrays:

<?php
    $user_info = array(
        'name'         => 'Joe Smith',
        'address'      => '123 Main St',
        'city'         => 'Anytown',
        'phone_number' => '555-555-5555',
        'email'        => 'joe.smith@example.com'
    );

Why does the indentation and spacing matter?

As I mentioned earlier, when I was trying to fix something in a plugin of mine that was poorly formatted, it was really difficult for me to isolate the problem. And that was a plugin that I wrote! Imagine if you were trying to read someone else’s code that was poorly formatted. This code, that you have never seen before, that is poorly formatted will be very difficult to read.

Now, if you are distributing your plugin to others, there may be a time when someone wants to read your code. Maybe they want to troubleshoot a bug or offer an improvement to an existing function. If your code is difficult to read they will likely stop before they have a solution.

Meaningful names in files and code

Meaningful file names

It is equally important to name your plugin’s files in a logical manner as it is to name the plugin’s folders logically. Could you imagine trying to troubleshoot a plugin, where you open the plugin’s folder and find something like this:

• /plugin-name
  • file-1.php
  • file-2.php
  • file-3.php
  • file-4.php

AHHH! That would be a disaster to figure out what each file is used for.

Instead, each file should contain a few lines of code that serve a similar purpose. For example, if your plugin creates shortcodes, you might want to create a file called shortcodes.php, that has all of the shortcode functions. If your plugin creates a custom post type “books”, you might name the file with the functions to create it books-cpt.php.

Meaningful naming in your code

Let’s drill down a little deeper. Let’s say your plugin has this function:

<?php
function function_1(){
 	echo 'This is my function';
}

Do you think that it would be possible that another plugin or theme developer could use the same function name? The problem with it is function_1 is just too generic.

All of your functions should be made up of two components:

• A unique prefix
• A description of what the function does

By prefixing our plugin’s functions, we’re reducing the likelihood that some other plugin developer will use the same function name as us.

Who cares, right? Well, if two functions with the same name are loaded on a site, it will trigger a fatal error. Generally, people frown on these errors, so it’s best to avoid them as much as possible.

Here are a few examples. Let’s say our function will display a logged in user’s first name.

<?php
function display_first_name(){
 	if( !is_user_logged_in() ){
 	 	echo 'Hello not logged in user';
 	} else {
 	 	$current_user = wp_get_current_user();
 	 	echo 'Hello ' . $current_user->user_firstname;
 	}
}

It would be pretty easy for another plugin developer to create a function with the exact same name display_first_name.

Now, let’s change this function name to have a unique prefix:

<?php
function my_plugin_name_display_first_name(){
 	if( !is_user_logged_in() ){
 	 	echo 'Hello not logged in user';
 	} else {
 	 	$current_user = wp_get_current_user();
 	 	echo 'Hello ' . $current_user->user_firstname;
 	}
}

By prefixing it with my plugin’s name we’re fairly confident that no other plugins will include a function with the same name.

You can also prefix it with an abbreviated version of your plugin’s name. For example, Easy Digital Downloads uses edd as a prefix to all of their functions. Sure, another plugin may have the same abbreviation, but it isn’t likely that they will have the same functions as Easy Digital Downloads.

Meaningful variables

In your PHP code, you will often times create variables to hold the output of a function or a value from the database.

It would be completely meaningless if your variables were something like $var1, $var2, $var3. Someone who is reading your code wouldn’t know what to expect the variables to output.

Instead, use a meaningful name each time you create a variable.

<?php
    //Good variable name
    $current_user = wp_get_current_user();
    //Bad variable name
    $a = wp_get_current_user();
}

Both of the variables in the example above have exactly the same value. But when reading the code it isn’t obvious what $a represents.

File organization

At a minimum, a plugin can be a single PHP file. However, most plugins are grouped in folders that contain all of the plugin’s files. Since each file in a given folder must have a unique name, grouping a plugin’s files in its own folder will prevent other plugins with similar names from overwriting, or otherwise conflicting with your plugin’s file.

Just think. If your plugin’s file was called “my-awesome-plugin.php” and someone else decided to also make “my-awesome-plugin.php”, one of the two would end up overwriting the other.

It is usually a good idea to give your plugin a meaningful name. Naming your plugin’s folder “scotts-plugin-1” isn’t meaningful. It might fall into some logical order if this was the first plugin I wrote, but it doesn’t tell me anything about what the plugin does. Something like “tabbed-account-area-for-easy-digital-downloads” is very descriptive. It tells us what the plugin does, and lets us know that it is for use with the plugin Easy Digital Downloads.

Folders

So your plugin’s files will all be contained within your super descriptive, well-named folder. This is great if you only have a few files, but what about if you have a few dozen files? Surely there should be some logical organization to those files as well.

Typically within the main plugin’s folder, you will see the main plugin file, a readme.txt file (more on that in a minute), and several folders. Those folders should help organize the rest of your plugin’s files in a logical manner.

Here is a sample layout of a plugin’s folder structure:

• /plugin-name
  • plugin-name.php
  • readme.txt
  • /languages
  • /includes
  • /admin
    • /js
    • /css
    • /images
  • /public
    • /js
    • /css
    • /images

Here we can clearly tell what folder contains the files that work on the admin side of the site, and the files that work on the public side of the site. It’s clear where the public facing CSS files are located, and where the admin JavaScript files are located.

Your plugin may not need all of these folders, and some of them may not make sense to be named this way. But this serves as a good example of a logical organizational structure for your plugin.

Including a readme.txt file

If you are going to host your plugin on WordPress.org’s plugin directory you will need to include a readme.txt file. This gives the plugin directory all of the information it needs to display on the plugin page. Here is a sample readme.txt file. You can also use a tool like the readme.txt file generator to help come up with a properly formatted file.

If you are not planning on distributing your file on WordPress.org you don’t need a readme.txt file. For example, if you are developing a plugin for your own personal use or are selling your plugin through your own website, you wouldn’t need one. It won’t hurt anything if you choose to include it though.