When choosing a name for your plugin, it's good practice to consider a name based on what your plugin actually does. For example, if you create an SEO-focused plugin, you wouldn't want to name it Bob's Plugin. Your audience would have no idea what your plugin actually does based on the plugin name. Your plugin name should be unique to your plugin and should also be descriptive of your plugin's purpose.

It's also a good idea to search the Plugin Directory on WordPress.org (http://wordpress.org/extend/plugins/) for similar plugins to avoid confusion. If you decide to name your plugin SEO Gold, and a plugin named SEO Silver already exists, there might be some confusion on whether your plugin is new or just a newer version of an old plugin. You don't want the first impression of your plugin to be met with confusion. Chapter 17, "Marketing Your Plugins," covers this in more detail.

It's highly recommended to store all your plugin files inside a folder within the plugins directory in WordPress. All plugins downloaded from the WordPress.org Plugin Directory are automatically structured in subfolders. This enables your plugin to easily contain multiple files and any other items you want to include, such as images. You can also include subfolders to help organize your plugin files better. The folder name should be the same as the main plugin filename. You shouldn't include any spaces or underscores in the folder name; instead use hyphens if needed. Subfolders and the hierarchical directory structure of the files are discussed further in the "Sanity Practices" section of this chapter.

When building a custom plugin, it's essential that you prefix everything with a unique prefix. This means all plugins files, function names, variable names, and everything included with your plugin. Why? Simple, one of the most common errors in plugins is using all too common names for function and variables. For example, if you have a function named update_options() and the user installs another plugin with the same function name, the website will break because you can't have two functions with the same name in PHP.

A good rule of thumb is to prefix everything with your plugin initials and your own initials. For instance if your name is Michael Myers and your plugin is named Halloween Revenge, you would prefix the function as mm_hr_update_options(). There is a strong chance no other plugin in the world exists with the same function name; therefore there is little risk of having conflicts with other plugins.

This is also a good rule for variable names. Don't use general names when creating variables. For instance, say your plugin creates and uses a variable called $post. That could cause unexpected results because $post is a global variable in WordPress containing the post data. If your plugin overwrites the data in $post and something else in WordPress expects the post data to still exist, you might have a serious problem. Instead you can use the same prefix method previously described and name your variable $mm_hr_post. This is a unique variable name most likely not used in any other plugin.

This book prefixes everything with boj_ (a mashup of the Authors' initials) and myplugin_ (assuming the fictitious plugin is named My Plugin) like so: boj_myplugin_function_name().

Keeping your plugin files organized is a key step in producing a professional plugin. Generally speaking, you should have only two files in your plugin folder: the primary plugin PHP file and your uninstall.php file. For organizational reasons, store all other plugin files in a subdirectory.

It is also recommended you split your plugin into several smaller files. One primary reason for doing so is for performance reasons. For instance, you should group all admin interface functions in a separate file. This allows you to conditionally include the admin code only when the user is viewing the admin side of WordPress:

<?php
if ( is_admin() ) {
    // we're in wp-admin
    require_once( dirname(__FILE__).'/includes/admin.php' );
}
?>

The preceding example uses the is_admin() conditional statement to verify the user is in the admin dashboard of WordPress. If so your plugin should include and process the /includes/admin.php file for your plugin.

Another important step to a professional plugin is maintaining a clean folder structure, which pertains to keeping all similar files together. For example, if your plugin requires JavaScript files, create a /js folder and store all the JavaScript files in this directory. If you have custom style sheet files, create a /css folder to store all your CSS files. Keep all images stored in a /images folder.

Now look at a standard folder structure for a plugin:

As you can see, keeping your files organized using a clean folder structure can make it much easier to track the flow of your plugin over time. It can also make it much easier for other plugin developers to follow your logic when they view your plugin's source code.

Following is an example of a plugin header:

<?php
/*
Plugin Name: My Plugin
Plugin URI: http://example.com/wordpress-plugins/my-plugin
Description: A brief description of my plugin
Version: 1.0
Author: Brad Williams
Author URI: http://example.com
License: GPLv2
*/
?>

Code snippet header-example.php

As you can see, the plugin header is straightforward. The only required line for WordPress to recognize your plugin is the plugin name, but it's good practice to fill in the entire header as shown.

The Plugin URI is a direct link to your plugin detail web page. The description is a short description of your plugin, which displays on the Plugin screen in WordPress. The version number is the current version of the plugin. WordPress uses the version number set here to check for new plugin updates at WordPress.org. The next two lines are the Author and Author URI. The Author is listed on the Plugin screen with a link to the Author URI set here. The final line is the software license the plugin is released under.

Figure 2-1 shows how your plugin header is rendered in WordPress.

Figure 2.1. FIGURE 2-1

The plugin Author's name, Brad Williams in this case, will link directly to the Author URI. The "Visit plugin site" text will link to the Plugin URI as defined in your plugin header. As you can see, both of these links can help users of your plugin find additional information about you and your plugin.

Below the plugin header comment block, it's a good idea to include the license for your plugin. This is not a requirement for your plugin to function, but anytime you release code to the public, it's a good idea to include a license with that code. This gives your users clear answers in how your plugin is licensed and how they can use your code. Chapter 17, "Marketing Your Plugins," covers this topic.

WordPress is licensed under the GNU General Public License (GPL) software license and as such any plugin distributed for WordPress should be compatible with the GPL. Following is an example of a standard GPL license comment block:

<?php
/*  Copyright YEAR  PLUGIN_AUTHOR_NAME  (email : PLUGIN AUTHOR EMAIL)

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/
?>

Code snippet license-example.php

Simply fill out the year, plugin author name, and email in the preceding license code. Now place the license code just below your plugin header. By including this software license, your plugin will be licensed under the GPL.

A common task in any plugin is referencing files and folders in your WordPress installation. You can reference files in your code in two ways: using the local server path or by using a standard URL. Think of the local server path as nothing more than the directory path on a computer. The local server path is generally used whenever you need to include something that is local on your server. A URL is typically used to link to something external to your server, but that doesn't mean you can't link to images and such using the URL path.

WordPress features the ability to move the wp-content directory to a different location. Because of this you shouldn't hardcode directory paths in WordPress, but rather use the available functions to determine the correct path.

Here's one common question in plugin development: What is the proper way to determine the local path to your plugin files? To determine the local path to your plugin, you need to use the plugin_dir_path() function. The plugin_dir_path() function extracts the physical location relative to the plugins directory from its filename.

<?php plugin_dir_path( $file ); ?>

Parameters:

Now look at an example on how to determine the local path to your plugin folder:

<?php
echo plugin_dir_path( __FILE__ );
?>

You can see you pass the __FILE__ PHP constant to the plugin_dir_path() function. This produces the full local server path to your plugin directory:

/public_html/wp-content/plugins/my-custom-plugin/

What if you need to get the local path to a file in a subdirectory inside your plugin directory? You can also use the plugin_dir_path() function along with the subdirectory and files you want to reference:

<?php
echo plugin_dir_path( __FILE__ ) .'js/scripts.js';
?>

This code would produce the following results:

/public_html/wp-content/plugins/my-custom-plugin/js/scripts.js

As you can see, this function will be instrumental in developing a solid WordPress plugin. Using the proper methods to access your plugin files and directories can ensure maximum compatibility with all WordPress installations, regardless of how custom it is.

Functions are also available to help determine URLs in WordPress. Following is a list of those functions:

The site_url() and home_url() functions are similar and can lead to confusion in how they work. The site_url() function retrieves the value as set in the wp_options table value for siteurl in your database. This is the URL to the WordPress core files. If your core files exist in a subdirectory /wordpress on your web server, the value would be http://example.com/wordpress.

The home_url() function retrieves the value for home in the wp_options table. This is the address you want people to visit to view your WordPress web site. If your WordPress core files exist in /wordpress, but you want your web site URL to be http://example.com the home value should be http://example.com.

The plugins_url() function will be one of your best friends when building plugins in WordPress. This function can help you easily determine the full URL to any file within your plugin directory.

<?php plugins_url( $path, $plugin ); ?>

Parameters:

For example, say you want to reference an image file to use as an icon in your plugin. You could easily accomplish this using the following example:

<?php
echo '<img src="' .plugins_url( 'images/icon.png', __FILE__ ). '">';
?>

The first parameter value you pass to the function is the relative path to the image file you want to include. The second parameter is the plugin file that you want to be relative, which in this case you can simply send in the PHP constant __FILE__. The preceding code would generate the HTML img tag as follows:

<img src="http://example.com/wp-content/plugins/my-custom-plugin/images/icon.png">

Following are some of the advantages to using the plugins_url() function to determine plugin URLs:

The plugin activation function is triggered when, you guessed it, a plugin is activated in WordPress. This function is called register_activation_hook(). Using this function is a great way to set some default options for your plugin. It can also verify that the version of WordPress is compatible with your plugin. The function accepts two parameters as shown here:

<?php register_activation_hook( $file, $function ); ?>

Parameters:

Now look at an example of this function in action:

<?php
register_activation_hook( __FILE__, 'boj_myplugin_install' );

function boj_myplugin_install() {
    //do cool activation stuff
}
?>

The first parameter you send the function is the path to your file, using the __FILE__ constant. This is a PHP constant that always contains the absolute path to the file it is called from. The second parameter is the unique function you want to call when your plugin is activated.

Now that you understand how the register_activation_hook() function works, look at a real-world example. Following is an example of how you can easily verify the version of WordPress is compatible with your plugin.

<?php
register_activation_hook( __FILE__, 'boj_install' );

function boj_install() {
    If ( version_compare( get_bloginfo( 'version' ), '3.1', '<' ) ) {
        deactivate_plugins( basename( __FILE__ ) ); // Deactivate our plugin
    }
}
?>

Code snippet version-requirement.php

Your install function boj_install() uses the get_bloginfo() function to retrieve the current version of WordPress the user runs. Next you use the PHP function version_compare() to verify the installed version of WordPress is at least 3.1. If the WordPress version is older than 3.1, deactivate your plugin using the deactivate_plugins() function.

Another common plugin activation technique is to set some default settings when your plugin is activated. Imagine your plugin has an entire page worth of options available. Chances are some of those options need to be defined for your plugin to work properly. Rather than forcing the user to visit your settings page and set those options, you can automatically set default options when the plugin is activated.

<?php
register_activation_hook( __FILE__, 'boj_install' );

function boj_install() {
    $boj_myplugin_options = array(
        'view' => 'grid',
        'food' => 'bacon',
        'mode' => 'zombie'
    );
    update_option( 'boj_myplugin_options', $boj_myplugin_options );
}
?>

The preceding code example creates an array of default options and stores them in WordPress when your plugin is activated. Chapter 7, "Plugin Settings," covers creating and saving options in WordPress in more detail.

Just as there is an activation function, there is also a deactivation function. This is called the register_deactivation_hook() function. This function is triggered when your plugin is deactivated in the WordPress Plugins screen. This function accepts the same two parameters as the previous activation function.

<?php register_ deactivation_hook( $file, $function ); ?>

Parameters:

Now look at an example of the deactivation function in action:

<?php
register_deactivation_hook( __FILE__, 'boj_myplugin_uninstall' );

function boj_myplugin_uninstall() {
    //do something
}
?>

The preceding example would execute your boj_myplugin_uninstall() function when your plugin is deactivated in WordPress.

When dealing with the deactivation function, you shouldn't include uninstall functionality when a plugin is deactivated. Imagine if you accidentally deactivate a plugin and upon reactivation you realize all your settings for that plugin have been deleted. Also, remember the WordPress automatic update feature deactivates all plugins prior to installing the new version of WordPress.

Think of your plugin as a piece of software installed on your computer. You expect that piece of software to have an easy way to uninstall it from your computer. You also expect the uninstaller to remove any trace of that software from your computer. A plugin in WordPress is no different; it's essentially a piece of software installed in WordPress. If users want to uninstall your plugin, you should provide the necessary uninstall functionality to remove all traces of the plugin from their WordPress site.

A good rule of thumb is to be considerate of your plugin user's data. For example if your plugin creates events as a custom post type, chances are the user does not want all of their events deleted if they uninstall your plugin. In that case you might want to ask the user if they want to delete all plugin data or not.

WordPress provides two different methods for uninstalling a plugin: the uninstall.php file and the uninstall hook.

The first method is the uninstall.php file. This is typically the preferred method because it keeps all your uninstall code in a separate file. To use this method, create an uninstall.php file and place it in the root directory of your plugin. If this file exists WordPress executes its contents when the plugin is deleted from the WordPress Plugins screen page. Now look at an example using the uninstall.php file:

<?php
// If uninstall not called from WordPress exit
if( !defined( 'WP_UNINSTALL_PLUGIN' ) )
    exit ();

// Delete option from options table
delete_option( 'boj_myplugin_options' );

//remove any additional options and custom tables
?>

The first thing you want to do is verify that WordPress is actually calling the uninstall.php file. Do this by verifying the WP_UNINSTALL_PLUGIN constant is defined. If it is not, immediately exit the script. This is a security measure to ensure this file is not executed except during the uninstall process of your plugin.

After you have verified this is a valid uninstall call, you can delete your plugin options from the database. The goal of a plugin uninstall script is to remove any trace of the plugin from the WordPress database. This includes deleting all options and dropping any custom tables that may have been created. You don't need to worry about deleting the actual plugin files or directories in this function. WordPress will do that for you once your uninstall script runs.

The second uninstall method available is the uninstall hook. If you delete a plugin in WordPress and uninstall.php does not exist, WordPress executes the uninstall hook (if it exists).

<?php register_uninstall_hook( $file, $function ); ?>

Parameters:

Now look at an example of the uninstall function in action:

<?php
register_activation_hook( __FILE__, 'boj_myplugin_activate' );

function boj_myplugin_activate() {

    //register the uninstall function
    register_uninstall_hook( __FILE__, 'boj_myplugin_uninstaller' );

}

function boj_myplugin_uninstaller() {

    //delete any options, tables, etc the plugin created
    delete_option( 'boj_myplugin_options' );

}
?>

As you can see, the register_uninstall_hook() should be called on activation and not on every plugin load. To do this you'll include the uninstall hook when the plugin is activated using the register_activation_hook(). Next call the uninstall function. Again pass the __FILE__ constant as the first parameter. The second parameter is your uninstall function that you want to execute.

Inside your boj_myplugin_uninstaller() function is where all uninstall procedures take place. Remember if the uninstall.php file exists in your plugins root folder, the uninstall hook won't actually execute.

As suggested in this section, there are many pitfalls to using the uninstall hook. It's a much cleaner, and easier, process to use the uninstall.php method described earlier for removing plugin settings and options when a plugin is deleted in WordPress.

One of the most obvious, yet commonly skipped steps, is code commenting. Commenting your plugin's source code is a quick and easy way to document exactly how your plugin works. There are many benefits to commenting your code. The major benefit to code commenting is to explain what your code actually does, in plain English.

Imagine writing an extremely complex plugin without a single comment. If you don't review the code for months and then return to it, you might have a hard time understanding what your code actually does. Now imagine other developers are reviewing your code; without comments it could take them a much longer time to follow your code logic and understand how your plugin functions. Comments are beneficial to everyone involved, so for everyone's sanity, always comment your code!

Nearly all functions in WordPress core contain inline documentation in PHPDoc form. PHPDoc is a standardized method of describing a function's usage in PHP comment form. Following is a basic example of a PHPDoc formatted function comment:

<?php
/**
 * Short description
 *
 * Longer more detailed description
 *
 * @param   type    $varname1   Description
 * @param   type    $varname2   Description
 * @return  type    Description
*/
function boj_super_function( $varname1, $varname2 ) {
    //do function stuff
}
?>

As you can see, the preceding PHPDoc comment helps to describe the function directly below the comment block. If I'm a developer looking over your plugin's code, I can quickly determine exactly how your function works, what parameters it accepts, and what I can expect returned without even reading your function's code. These comments are also used by more visual tools such as PHPDocumentor and PHPXref.

Variable and function names should always be written in lowercase. Words should also be separated using underscores. Following is an example showing the proper way to name a function and variable:

<?php
function boj_myplugin_function_name ( $boj_myplugin_variable ) {
    //do something
}
?>

Files should also be named using only lowercase letters; however, filenames should use hyphens to separate words and not underscores. For example you might name your plugin: boj-plugin-name.php.

PHP enables you to define strings using single or double quotes. In WordPress it's recommended to use single quotes whenever possible. One of the benefits of using single quotes is you rarely need to escape HTML quotes in a string. Following is an example showing how to echo a link using the single quote method:

<?php
echo '<a href="http://example.com/">Visit Example.com</a>';
?>

You can also use the double quote method when concatenating a string in PHP. For example, look at a simple way to insert a variable for your website URL:

<?php
$boj_myplugin_website = 'http://example.com/';
echo "<a href='$boj_myplugin_website'>Visit Example.com</a>";?>

Set the $boj_myplugin_website variable to the URL you want to include in your HTML link. Then concatenate the string to include the web site URL in your echo statement.

Indentation should always reflect the logical structure of the code. This means using real tabs, and not spaces, when indenting your code. As an example look at a poorly indented if statement:

if ( condition ) {
echo 'Yes';
} elseif ( condition2 ) {
echo 'No';
}

The preceding code logic is hard to follow because no indentation reflects the logical structure of the if statement. Now look at the same code sample using proper indentation:

<?php
if ( condition ) {
    echo 'Yes';
} elseif ( condition2 ) {
    echo 'No';
}
?>

Notice how using proper indentation makes reading the logic of the preceding if statement much easier to follow. You can easily skim this code and understand the outcome of the statement. This is why proper indentation is a must with any code you write.

Braces should always be used for multiline blocks of code. The brace should be positioned on the same line as the conditional statement you are checking. Look at an example using the proper bracing technique:

<?php
if ( condition ) {
    action1();
    action2();
} elseif ( condition2 || condition3 ) {
    action3();
    action4();
} else {
   defaultaction();
}
?>

If you have an extremely long block of code, it's a good idea to put a short comment at the ending brace to help determine at a glance what that ending brace actually ends:

<?php
if ( condition ) {
    action1();
    action2();
} elseif ( condition2 || condition3 ) {
    action3();
    action4();
} else {
   defaultaction();
} //end of condition check
?>

Spaces should always be used after commas and on both sides of logical and assignment operators. Now look at a few different examples using the proper spacing methods:

<?php
if ( $foo == 34 ) {
    //do something
}

foreach ( $foo as $bar ) {
    //do something
}

$foo = array( 34, 16, 8 );

function super_function( $param1 = 'foo', $param2 = 'bar' ) {
    //do something
}
?>

Notice the spacing technique for each statement. This makes reading and following your code logic much easier because the code examples are clean and consistent throughout.

You shouldn't use the shorthand PHP tags ( <? ?> ) in your code. The reason for this is that shorthand PHP tags must be enabled on your server before they will function. Many hosting configurations have this feature disabled by default, which means your plugin would immediately break when activated in WordPress. Instead, you should wrap your PHP code in standard tags: <?php ?>

When making database calls in WordPress you may need to write custom SQL statements to query the proper data from the database. SQL statements can be broke into multiple lines if the complexity of the statement warrants it. Even though SQL is not case-sensitive, it's good practice to capitalize the SQL commands in the statement.

SELECT username FROM table1 WHERE status = 'active'

Chapter 6, "Plugin Security," discusses the proper way to use SQL statements in WordPress.