Headzoo

Writing a WordPress plugin is really very simple. This post is going to guide you through the process of writing your first plugin. Of course you need to know PHP before you can write a plugin, and if you don’t know PHP, you can learn it using my Barney style PHP tutorials.

The first thing you need to understand before writing a plugin for WordPress, is that your PHP scripts become part of WordPress. WordPress uses the include() statement to merge your plugin code into the core of the main scripts. That means you plugin has access to all the functions, variables, methods, constants, etc, defined within WordPress.

This also means that if your plugin crashes, WordPress crashes, and no one likes it when a plugin brings down their entire site.

All plugins are PHP scripts, as already stated. Your plugins can contain any number of scripts, but there must be a primary plugin script. It’s that primary plugin script that is included when WordPress is loading the plugins, and from there, your primary script can include() any other scripts that it needs.

All primary plugin scripts need a comment header that tells WordPress some basic information about the plugin. The format of the header is this:

<?php
/**
 Plugin Name: Your Plugin Name
 Plugin URI: http://www.somesite.com/yourpluginname
 Version: 1.0
 Description: Just a basic plugin
 Author: Your Name
 Author URI: http://www.somesite.com
 */
?>

As you can see this is just a comment block, with colon separated key value pairs. It’s nothing fancy, but it’s enough to tell WordPress all about your plugin. Although your plugins can include any number of files, only one of the PHP scripts should have this comment block. That is your primary plugin script.

Your plugin goes into the /wp-content/plugins directory. You can also place your plugin files in a sub directory of the /wp-content/plugins directory, like /wp-content/plugins/myplugin. If your plugin includes more than one script, then it’s recommended you keep them in a sub directory so that the /wp-content/plugins directory stays nice and tidy.

Hooks

There are two primary functions used by plugins to “hook” into the input/output functions built into WordPress: add_action() and add_filter(). Lets start by going over add_filter(), since it has the most uses.

The add_filter() function does what it sounds like. It lets you filter data as it’s flying around inside of WordPress. The function requires two parameters: The name of the “hook”, and a valid callback function. Here is a quick example:

<?php
/**
 Plugin Name: My Plugin
 Author: Your Name
 */
 
add_filter('the_content', 'myfunction');
 
function myfunction($content) {
     return strtolower($content);
}
?>

Believe it or not, that is a fully functioning plugin. When someone visits your site, your blog posts will be displayed in all lower case. This certainly isn’t a very powerful plugin, or even a very useful one, but it does demonstrate the use of the add_filter() function.

The first parameter for the add_filter() function is a filter hook name. The name describes what data you want to filter. In the example above, we want to filter ‘the_content’, which means the content of a blog post.

The second parameter is the name of a function to pass the content through. In the above example, we gave to the add_filter() function the name of our ‘myfunction’ function.

So what happens when someone visits the blog? Just prior to sending the blog content to the browser, WordPress will run the content of the post through your myfunction() function, passing the content of the post as the one and only parameter to myfunction(). Your myfunction() function is expected to do something to the content, and then return it. In this example, we made the content all lower case, and then returned that.

There are many filter hooks in WordPress, and each one will pass different parameters to your callback functions. You will need to reference the WordPress codex for a list of all hooks, and the parameters that are passed to your callback functions.

The add_action() function works similar to the add_filter() function, but instead of being used to filter data, it is used to call a function at a specific point in time during the execution of WordPress. Lets look at an example:

<?php
/**
 Plugin Name: My Plugin
 Author: Your Name
 */
 
add_action('wp_head', 'myfunction');
 
function myfunction() {
     echo '<script type="text/javascript">alert("hello world");';
}
?>

This is another simple, but fully functional plugin. It does one thing: When someone visits the blog, it places a little JavaScript inside the document’s <head></head> tags. In this case, when the document loads, a JavaScript alert will pop-up saying “hello world”.

Just like add_filter(), the first parameter to add_action() is the name of an action hook, and the second is the name of a function. The ‘wp_head’ hook used in the example above tells WordPress to call your function inside of the document’s head. Also like the add_filter() function, there are dozens of action hooks, and you will need to check the WordPress codex for a list of them all.

Putting it all together

You now know about the add_filter() and add_action() functions, and you can do quite a lot with just those two functions, and a couple functions of your own. Lets write a full blown plugin that uses both of those functions.

<?php
/**
 Plugin Name: My Plugin
 Plugin URI: http://www.somesite.com/myplugin
 Version: 1.0
 Description: My first plugin
 Author: Your name
 Author URI: http://www.somesite.com
 */
 
add_filter('the_title', 'myplugin_the_title');
add_filter('the_content', 'myplugin_the_content');
add_action('wp_footer', 'myplugin_wp_footer');
 
function myplugin_the_title($title) {
	return ucwords(strtolower($title));
}
 
function myplugin_the_content($content) {
	$content = str_replace('some site', '<a href="http://www.somesite.com">some site', $content);
	return $content;
}
 
function myplugin_wp_footer() {
	echo '<!--Generated by My Plugin-->';
}
?>

This plugin does three things: 1) It properly capitalizes post titles uses the ‘the_title’ filter hook. 2) It replaces all instances of ’some site’ in a blog post with a link to ‘http://www.somesite.com’. 3) And finally it places an HTML comment in the document’s footer, letting the whole world know the blog is using your plugin.

Final Thoughts

Between WordPress and all the other plugins a person might have installed, there are hundreds of functions and variables, all trying to play nice with each other. Because of that it’s important that you prefix your function names with something unique, like the name of your plugin. The same goes for any variables you create in the global scope.

You can use the $wpdb object to make queries to the database. It’s the primary object used by WordPress to make queries, and it’s available to your plugin to use. The database table prefix set in the wp-config.php script is stored in the variable $table_prefix.

The add_filter() and add_action() functions can take a third parameter, which is a number between 1 and 10. This is a number that describes the priority of your filter or action. If you don’t specifiy a number, your action or filter is given a 10 by default.

Happy plugin developing!