Writing your First WordPress Plugin

In this tutorial we will show you how to create your first WordPress plugin.  The goal of the plugin will be simple so that we can focus on the plugin requirements and structure instead of focusing on the plugin functionality itself.  As such – this tutorial is an excellent step along the way to learning how custom plugins work.

Writing your first WordPress Plugin

In order to create our plugin we will cover the following topics:

  • Product Design of the Plugin
  • Create Needed Plugin Structure
  • Create Necessary Plugin Hooks
  • Activate and Test the Plugin
  • Finalize and Cleanup

 

Product Design of the Plugin

The first step in any plugin project is to define proper goals and expectations for the plugin.  I.E. – what is its purpose?  We do this for several reasons:

  • Existing Plugins: The WordPress community and plugin archive is very large.  A similar plugin may already exist saving you time.
  • Encourages Performant Code:  A well defined plan helps to limit unneeded functionality.  Excess hooks in a plugin will slow down your site – only add the functionality thats need.
  • Architecture Overview:  A proper plan from your plugin will help you understand what action hooks and filters you will need to use and how to organize your calls.

In our case, we want to make a plugin that will display a custom footer on every post on our site.  In order to do this, we need to first plan out what the admin and end user flow will look like upon activating the plugin. Upon activating the plugin, we will want the following flows to be supported:

  • No admin controls in our first version.  Hard code footer content for now.
  • On post pages, display saved footer content at the end of every post.

In this simplistic first version, our necessary hooks to utilize will be minimal.  In this case we will only want to hook into the filter entitled “the_content”.  More information about this filter hook will be provided later in this tutorial.

 

Create Needed Plugin Structure

When you create a plugin you need to setup your code and files in a certain way in order for WordPress to recognize it and properly parse it as a plugin.  Your first task in this endeavor is to create a folder to house your plugin files.  For this tutorial we will name our folder “wpdh-simple-footer”.  Place this folder inside the “wp-content/plugins/” folder of your WordPress installation.

Within that folder, you now need to create a php file named “index.php”.  Once completed you should see something similar to this file view:

WordPress Plugin Tutorial - Filesystem Structure

Now we need to open up that index.php file.  Use any IDE you prefer.  Once open, we need to add certain pieces of meta-data in the form of a comment section.  WordPress calls this data header information and WordPress uses it to properly parse and display details about your plugin in the admin control panels.

<?php
/*
Plugin Name: Plugin Tutorial - Simple Footer
Plugin URI: http://www.wpdevhub.com
Description: A simple plugin to add a footer to every post.
Version: 1.0
Author: WPDevHub
Author URI: http://www.wpdevhub.com
*/

Detailed information about these headers can be found at the following url: https://developer.wordpress.org/plugins/the-basics/header-requirements/

With this information added we have the basic structure for our plugin and can now move onto defining our functionality.

 

Create Necessary Plugin Hooks

Our next task is to define out what plugin hooks we want to define.  A plugin hook is a request for WordPress to execute a certain piece of code at a designated point in the loading sequence for a given page.  Think of these as event listeners and handlers.

Hooks in WordPress are called either via Actions or Filters.  In a very simplistic manner:

  • Actions are certain timeline points during pageload such as “get_header” which is called before the header template file is called.
  • Filters pass a piece of page content and allows you to manipulate it such as “the_content” which passes the content of the post to be displayed.

Our plugins design is very simple.  For that reason we are only going to hook into one single action hook entitled “the_content”.  In our case, we will add a footer to the existing post content and then return the combined data.

When you define an action hook or filter, you call either “add_action” or “add_filter” functions.  The first argument is the name of the filter or action being called and the second parameter is the callback function that should be run when the filter or action is executed.

Here is our code to register our filter hook:

// Add the Action Hook for the_content
add_filter('the_content', 'wpdh_get_footer_display');

In this case we registered the filter hook for “the_content” and told it to call the function entitled “wpdh_get_footer_display”

Now that our filter hook is registered, we need to define the code to execute when this hook is called.  In this plugin tutorial we are going to create a function that will take in the posts content, add a footer to it and return the combined data.

// Function that will display the footer contents when called
function wpdh_get_footer_display($content) {

    // make sure it is a single post and not a blog roll, archive page, etc
    if(is_single()) {
        $content .= "<p>Footer content to be added to every post.</p>";
    }
    
    // Return the post contents
    return $content;
}

You may have noticed the “is_single” function call.  This call will simple check to see if we are displaying one single post or a collection of posts.  That way we only display this footer on a single page display and not on the blog roll or archive pages, etc.

 

Activate and Test the Plugin

With our plugin code created, we are now ready to open the WordPress administration panel and test out the plugin.  Navigate to the Plugins admin page and you should see your plugin listed.

WordPress Plugin Tutorial - MetaData Info

Hit the link entitled “Activate”.  You should then see a success message at the top of the page.

WordPress Plugin Tutorial - Activation

At this point our plugin is now activated and should be functional.  Let’s create a quick post using generic “Lorem ipsum” data.

WordPress Plugin Tutorial - Editor

Once the article is created, select the option to view the article.  You should now see the article contents, plus our simple footer content added to it.

WordPress Plugin Tutorial - Example Post

Looks like everything is working!

 

Finalize and Cleanup

Your last step when creating a plugin is around finalizing your plugin details and cleaning up.  Let’s start by looking at the entire code block we ended up creating.

<?php
/*
Plugin Name: Plugin Tutorial - Simple Footer
Plugin URI: http://www.wpdevhub.com
Description: A simple plugin to add a footer to every post.
Version: 1.0
Author: WPDevHub
Author URI: http://www.wpdevhub.com
*/

// Add the Action Hook for the_content
add_filter('the_content', 'wpdh_get_footer_display');

// Function that will display the footer contents when called
function wpdh_get_footer_display($content) {

    // make sure it is a single post and not a blog roll, archive page, etc
    if(is_single()) {
        $content .= "<p>Footer content to be added to every post.</p>";
    }

    // Return the post contents
    return $content;
}

Take notice to the function name we used.  Notice that it begins with the text “wpdh_”.  When developing plugins for a large Open Source community such as WordPress it is important to design your code in a non obtrusive manner.  In this case we are name spacing our functions (and variables) so that they unique.  The hope is that no other developer in the community also has a function named “wpdh_get_footer_display”.  Our custom prefix helps to keep names unique.

You may also notice that we are using certain coding standards within our code.  Due to the large size of the WordPress community, it is again important that we adhere to similar coding standards throughout our plugins and themes.  These coding standards can be found here: https://codex.wordpress.org/WordPress_Coding_Standards

 

Conclusion

WordPress plugins can be as simple or as complicated as we make them.  Once we get the base structure up, we can continue to build and expand our functionality to add powerful features onto an already powerful core.