Join 9,000+ Readers

Beginner’s Guide to the WordPress Plugin System

by Jake Rocheleau

on February 14, 2013

in Wordpress

By searching in Google you can find a lot of specific WordPress tutorials related around plugins. However there are not too many guides which explain an overview of the system, best practices, and just getting started with plugins in general. Thus I want to fill the void and hopefully offer some great tips for newcomers.

coding a new wordpress plugin howto open source codes

In this article I will present the methods of building a WordPress plugin from top-to-bottom. We can look into just the minimum requirements for a plugin to exist, and then extend functionality as needed. The conventions are not overly complicated if you have a decent handle on PHP and the WordPress syntax.

Basic Plugin Structure

Most developers start out by asking how a plugin gets formed and molded. We can use even just a single PHP file to do this, but most plugins are separated into their own folders. This helps with organization and makes things easier if you need to add more files in the future.

Now another important piece is the comment section which accompanies every single plugin. The main file should be named the same as your plugin folder, such as my-simple-plugin.php. Inside the file we are including a header section with a set of comment lines describing metadata which appears in the WordPress admin panel. Here is a sample template you may copy from:

<?php
/*
Plugin Name: Simple Plugin
Plugin URI: http://www.colorburned.com/
Description: Doesn't really do anything helpful.
Version: 1.0
Author: Your Name
Author URI: http://www.google.com/
*/
?>

As you can see the information is pretty standard and not very difficult to work with. It shouldn’t take any more than a few minutes to put this together on each plugin. I recommend saving this template somewhere in your code snippets so it is an easy copy/paste job each time.

The Activation

If you save this file into your /wp-content/plugins/ folder and then log into the backend admin panel you should see the plugin name ready to activate. Granted we haven’t added any codes into the plugin so it will not do anything just yet. But it literally is this easy to get something added into WordPress.

However there are not any plugins which do nothing, so it’s likely you will want to include some code. I can offer some more helpful code templates but ultimately the programming logic should come from you. This is almost no different than coding inside your theme’s functions.php file. We can use filters, actions, shortcodes, and even just define functions to be added right inside your template PHP code.

So as an example we might code a function named msp_output_hello_world() which displays this text wherever you add the function. I have prefixed the function name with an abbreviation MSP which stands for My Simple Plugin. It’s a good rule of thumb to prefix your function names with something(unless you are programming in Object-Oriented classes). There are thousands of custom WP plugins and core functions which can often lead to overlaps in naming conventions.

Defining Local Resources

Targeting local plugin resources will allow all your code to quickly access local images or documents from any WP install. It is an important trait which should be supported by almost any plugin developer. Using this method you could have local resources which are still included regardless of the page hierarchy.

I found a fantastic article on Smashing Magazine about things WP developers should know which includes a sample code snippet. This will define four new special variables which are named constants. Their values will adapt to any server environment but they cannot be changed from other codes in PHP. This functionality is crucial so that the information can’t be manipulated by other functions in the script.

if (!defined('MYPLUGIN_THEME_DIR'))
    define('MYPLUGIN_THEME_DIR', ABSPATH . 'wp-content/themes/' . get_template());

if (!defined('MYPLUGIN_PLUGIN_NAME'))
    define('MYPLUGIN_PLUGIN_NAME', trim(dirname(plugin_basename(__FILE__)), '/'));

if (!defined('MYPLUGIN_PLUGIN_DIR'))
    define('MYPLUGIN_PLUGIN_DIR', WP_PLUGIN_DIR . '/' . MYPLUGIN_PLUGIN_NAME);

if (!defined('MYPLUGIN_PLUGIN_URL'))
    define('MYPLUGIN_PLUGIN_URL', WP_PLUGIN_URL . '/' . MYPLUGIN_PLUGIN_NAME);

$image = MYPLUGIN_PLUGIN_URL . '/images/my-image.jpg';
$style = MYPLUGIN_PLUGIN_URL . '/css/my-style.css';
$script = MYPLUGIN_PLUGIN_URL . '/js/my-script.js';
$themelogo = MYPLUGIN_THEME_DIR . '/images/logo.png';

Code Source

Each of the four constants may be used anywhere in the plugin code. This should be helpful in saving you some headaches down the road. Development is very tricky and trying to reinvent the wheel can be a huge waste of time.

Using WordPress Shortcodes

I am sure you have seen these small brackets surrounding WordPress shortcodes. These may be defined inside your function code and used to call any method within your plugin. This could be our Hello World function as defined earlier. Or it could be pulling the most popular blog posts from the past year out of our database and listing them in an unordered list.

The possibilities allow you to include dynamic functions within your static WordPress posts or pages. Some more helpful examples of shortcodes may include contact forms, video/audio players, image galleries, or embedded media.

add_shortcode('msphello', array($this, 'msp_output_hello_world');

Assuming we still have the same function from before, this single line of code will define a new shortcode by the tag [msphello]. Then it will call our function and echo the text onto any page we choose. Now one other important tidbit is to include the parameter variable $attributes inside our function definition like so:

function msp_output_hello_world($attributes) {
  // code here
}

The variable name could be anything you choose such as $atts or $attrs. As long as this is consistent then we can always use the same variable throughout the shortcode functions. These attributes allow you to add parameters into the shortcode tag which will be reflected inside PHP.

So if we wrote the call [msphello name=Jeff] then we can check for this name inside PHP and display it. Otherwise it’ll just replace this name variable with a string “World”, and we get the original message instead. Here is what the basic function code might look like:

function msp_output_hello_world($attributes) {
    extract(shortcode_atts(array(
        'name' => 'World',
    ), $attributes));

    echo 'Hello, '.$name.'!';
}

Related Links

Final Thoughts

Hopefully this article proves to be a useful reference guide to some newer WordPress developers. Plugins are such a fantastic solution for extending the possibilities of your website. And since WordPress is open source you can seek help from other programmers if you run into a wall. For more detailed support please consider joining the WordPress StackExchange community which is full of talented plugin developers.

About Jake Rocheleau

Jake is a freelance writer and web developer. He writes articles for numerous blogs on freelancing, Wordpress, CSS3, and jQuery. You can find him all throughout Google and follow his tweets @jakerocheleau. Connect with Jake on Google +