WordPress 3 Plugin Development Essentials

Create your own powerful, interactive plugins to extend and add features to your WordPress site

WordPress is a popular content management system (CMS), most renowned for its use as a blogging / publishing application. According to usage statistics tracker, BuiltWith (http://builtWith.com), WordPress is considered to be the most popular blogging software on the planet—not bad for something that has only been around officially since 2003.

Before we develop any substantial plugins of our own, let's take a few moments to look at what other people have done, so we get an idea of what the final product might look like. By this point, you should have a fresh version of WordPress installed and running somewhere for you to play with. It is important that your installation of WordPress is one with which you can tinker. In this article by Brian Bondari and Everett Griffiths, authors of WordPress 3 Plugin Development Essentials, we will purposely break a few things to help see how they work, so please don't try anything in this article on a live production site.

Deconstructing an existing plugin: "Hello Dolly"

WordPress ships with a simple plugin named "Hello Dolly". Its name is a whimsical take on the programmer's obligatory "Hello, World!", and it is trotted out only for pedantic explanations like the one that follows (unless, of course, you really do want random lyrics by Jerry Herman to grace your administration screens).

Activating the plugin

Let's activate this plugin so we can have a look at what it does:

1. Browse to your WordPress Dashboard at http://yoursite.com/wp-admin/.
2. Navigate to the Plugins section.
3. Under the Hello Dolly title, click on the Activate link.

   

You should now see a random lyric appear in the top-right portion of the Dashboard. Refresh the page a few times to get the full effect.

Examining the hello.php file

Now that we've tried out the "Hello Dolly" plugin, let's have a closer look. In your favorite text editor, open up the /wp-content/plugins/hello.php file. Can you identify the following integral parts?

• The Information Header which describes details about the plugin (author and description). This is contained in a large PHP /* comment */.
• User-defined functions, such as the hello_dolly() function.
• The add_action() and/or add_filter() functions, which hook a WordPress event to a user-defined function.

It looks pretty simple, right? That's all you need for a plugin:

• • An information header
  • Some user-defined functions
  • add_action() and/or add_filter() functions
    1. In your WordPress Dashboard, ensure that the "Hello Dolly" plugin has been activated.
    2. If applicable, use your preferred (s)FTP program to connect to your WordPress installation.
    3. Using your text editor, temporarily delete the information header from wpcontent/ plugins/hello.php and save the file (you can save the header elsewhere for now). Save the file.
    4. Refresh the Plugins page in your browser.
    5. You should get a warning from WordPress stating that the plugin does not have a valid header:

       

       Unlock access to the largest independent learning library in Tech for FREE!

       Get unlimited access to 7500+ expert-authored eBooks and video courses covering every tech area you can think of.

       Renews at $19.99/month. Cancel anytime

       START FREE TRIAL

    1. Ensure that the "Hello Dolly" plugin is active.
    2. Open the /wp-content/plugins/hello.php file in your text editor.
    3. Immediately before the line that contains function hello_dolly_get_lyric, type in some gibberish text, such as "asdfasdf" and save the file.
    4. Reload the plugins page in your browser.
    5. This should generate a parse error, something like: pre width="70">

       Parse error: syntax error, unexpected T_FUNCTION in /path/to/
       wordpress/html/wp-content/plugins/hello.php on line 16

    • Author: Listed below the plugin name
    • Author URI: Together with "Author", this creates a link to the author's site
    • Description: Main block of text describing the plugin
    • Plugin Name: The displayed name of the plugin
    • Plugin URI: Destination of the "Visit plugin site" link
    • Version: Use this to track your changes over time

Now that we've identified the critical component parts, let's examine them in more detail.

Information header

Don't just skim this section thinking it's a waste of breath on the self-explanatory header fields. Unlike a normal PHP file in which the comments are purely optional, in WordPress plugin and theme files, the Information Header is required! It is this block of text that causes a file to show up on WordPress' radar so that you can activate it or deactivate it. If your plugin is missing a valid information header, you cannot use it!

Exercise—breaking the header

To reinforce that the information header is an integral part of a plugin, try the following exercise:

After you've seen the tragic consequences, put the header information back into the hello.php file.

This should make it abundantly clear to you that the information header is absolutely vital for every WordPress plugin. If your plugin has multiple files, the header should be inside the primary file—in this article we use index.php as our primary file, but many plugins use a file named after the plugin name as their primary file.

Location, name, and format

The header itself is similar in form and function to other content management systems, such as Drupal's module.info files or Joomla's XML module configurations—it offers a way to store additional information about a plugin in a standardized format. The values can be extended, but the most common header values are listed below:

For more information about header blocks, see the WordPress codex at: http://codex.wordpress.org/File_Header.

In order for a PHP file to show up in WordPress' Plugins menu:

• The file must have a .php extension.
• The file must contain the information header somewhere in it (preferably at the beginning).
• The file must be either in the /wp-content/plugins directory, or in a subdirectory of the plugins directory. It cannot be more deeply nested.

Understanding the Includes

When you activate a plugin, the name of the file containing the information header is stored in the WordPress database. Each time a page is requested, WordPress goes through a laundry list of PHP files it needs to load, so activating a plugin ensures that your own files are on that list. To help illustrate this concept, let's break WordPress again.

Exercise – parse errors

Try the following exercise:

Yikes! Your site is now broken. Why did this happen? We introduced errors into the plugin's main file (hello.php), so including it caused PHP and WordPress to choke.

Delete the gibberish line from the hello.php file and save to return the plugin back to normal.

The parse error only occurs if there is an error in an active plugin. Deactivated plugins are not included by WordPress and therefore their code is not parsed. You can try the same exercise after deactivating the plugin and you'll notice that WordPress does not raise any errors.

Bonus for the curious

In case you're wondering exactly where and how WordPress stores the information about activated plugins, have a look in the database. Using your MySQL client, you can browse the wp_options table or execute the following query:

SELECT option_value FROM wp_options WHERE option_name='active_
plugins';

The active plugins are stored as a serialized PHP hash, referencing the file containing the header. The following is an example of what the serialized hash might contain if you had activated a plugin named "Bad Example". You can use PHP's unserialize() function to parse the contents of this string into a PHP variable as in the following script:

<?php
$active_plugin_str = 'a:1:{i:0;s:27:"bad-example/bad-example.
php";}';
print_r( unserialize($active_plugin_str) );
?>

And here's its output:

Array
(
[0] => bad-example/bad-example.php
)