In this article by Vladimir Prelovac, we will learn to create our first functional WordPress plugin and learn how to interact with the WordPress API (this is the WordPress interface to PHP) on the way. The knowledge you will gain in this article alone will allow you to write a lot of similar plugins.
Let’s get moving! This article is extracted from the “WordPress Plugin Development ” book. In this article, you will learn:
- Creating a new plugin and having it displayed in the plugins admin panel
- Checking the WordPress version and control activation of the plugin
- Accessing API features—for example the title and permalink URL of each post
- Using WordPress hooks to execute your plugin code when it’s needed
- Using conditional tags to control the flow of your plugins
You will learn these by creating a Social Bookmarking type of plugin that adds a Digg button to each post on your blog
As you probably know, Digg is a very popular service for promoting interesting content on the Internet. The purpose of a Digg button on your blog is to make it easier for Digg users to vote for your article and also to bring in more visitors to your blog.
The plugin we’ll create in this article will automatically insert the necessary code to each of your posts. So let’s get started with WordPress plugin development!
Plugging in your first plugin
Usually, the first step in plugin creation is coming up with a plugin name. We usually want to use a name that is associated with what the plugin does, so we will call this plugin, WP Digg This. WP is a common prefix used to name WordPress plugins.
To introduce the plugin to WordPress, we need to create a standard plugin header. This will always be the first piece of code in the plugin file and it is used to identify the plugin to WordPress.
Time for action – Create your first plugin
In this example, we’re going to write the code to register the plugin with WordPress, describe what the plugin does for the user, check whether it works on the currently installed version of WordPress, and to activate it.
- Create a file called wp-digg-this.php in your favorite text editor. It is common practice to use the plugin name as the name for the plugin file, with dashes ‘-’ instead of spaces.
- Next, add a plugin information header. The format of the header is always the same and you only need to change the relevant information for every plugin:
Plugin Name: WP Digg This
Description: Automatically adds Digg This button to your posts.
Author: Vladimir Prelovac
Author URI: http://www.prelovac.com/vladimir
Plugin URI: http://www.prelovac.com/vladimir/wordpress-plugins/
- Now add the code to check the WordPress version:
/* Version check */
$exit_msg='WP Digg This requires WordPress 2.5 or newer.
- Upload your plugin file to the wp-content/plugins folder on your server using your FTP client.
- Go to your WordPress Plugins admin panel. You should now see your plugin listed among other plugins:
- This means we have just completed the necessary steps to display our plugin in WordPress. Our plugin can be even activated now—although it does not do anything useful (yet).
What just happened?
We created a working plugin template by using a plugin information header and the version check code. The plugin header allows the plugin to be identified and displayed properly in the plugins admin panel. The version check code will warn users of our plugin who have older WordPress versions to upgrade their WordPress installation and prevent compatibility problems.
The plugin information header
To identify the plugin to WordPress, we need to include a plugin information header with each plugin.
The header is written as a PHP comment and contains several fields with important information.
This code alone is enough for the plugin to be registered, displayed in the admin panel and readied for activation.
If your future plugin has more than one PHP file, the plugin information should be placed only in your main file, the one which will include() or require() the other plugin PHP files.
Checking WordPress versions
To ensure that our plugin is not activated on incompatible WordPress versions, we will perform a simple WordPress version check at the very beginning of our code.
WordPress provides the global variable $wp_version that provides the current WordPress version in standard format. We can then use PHP function version_compare() to compare this and our required version for the plugin, using the following code:
// do something if WordPress version is lower then 2.6
If we want to stop the execution of the plugin upon activation, we can use the exit() function with the error message we want to show.
In our case, we want to show the required version information and display the link to the WordPress upgrade site.
$exit_msg='WP Digg This requires WordPress 2.6 or newer. <a
While being simple, this piece of code is also very effective. With the constant development of WordPress, and newer versions evolving relatively often, you can use version checking to prevent potential incompatibility problems.
The version number of your current WordPress installation can be found in the footer text of the admin menu. To begin with, you can use that version in your plugin version check (for example, 2.6).
Later, when you learn about WordPress versions and their differences, you’ll be able to lower the version requirement to the minimal your plugin will be compatible with. This will allow your plugin to be used on more blogs, as not all blogs always use the latest version of WordPress.
Checking the plugin
You can go ahead and activate the plugin. The plugin will be activated but will do nothing at this moment.
Time for Action – Testing the version check
- Deactivate the plugin and change the version check code to a higher version. For example, replace 2.6 with 5.0.
- Re-upload the plugin and try to activate it again. You will see a WordPress error and a message from the plugin:
What just happened?
The version check fails and the plugin exits with our predefined error message. The same thing will happen to a user trying to use your plugin with outdated WordPress installation, requiring them to update to a newer version.
Have a go Hero
We created a basic plugin that you can now customize.
- Change the plugin description to include HTML formatting (add bold or links to the description).
- Test your plugin to see what happens if you have two plugins with the same name (upload a copy of the file under a different name).