Writing Your First WordPress Plugin

I never wrote a wordpress plugin before, so when I set out to learn how they work, I was surprised to see how easy it is to create one. One would think that there would be lot’s of setup and a lot of digging in wordpress’ iinternals. But this is not the case. The WordPress plugin API is surprisingly straightforward and clean. A simplest plugin you could think of would be this simple Hello World plugin:

<?php
/*
	Plugin Name: Helo World
*/ 
?>

What does this plugin do? Absolutely nothing, except for showing up in your plugin management screen:

Hello World
click to enlarge

Worpress scans every php file in the wp-content/plugins directory and parses through the comments in those files to create the entries in the plugin manager. You write the comments, and they magically appear in those boxes. I will show you a full comment block in my next example.

Let’s write a very simple plugin – a word filter for your comments. What is a word filter? It’s a script that will replace occurrences of one word with another. You can use word filters to censor obscenities from your comments, or just mess with your readers by swapping words like male and female, straight and gay, or perhaps if your blog is popular enough to attract the First Poster change “first” to “I’m a looser”. In my example I will try to switch foo into bar and test into done.

For that purpose I set up two fake comments on my test blog:

Original Comments

If the plugin works, all the foos and test should change to bars and dones. I will show you the plugin first, and then explain the tricky bit(s):

<?php
/*
Plugin Name: Test Plugin
Plugin URI: http://example.com/
Description: This plugin is Awesome.
Author: Lukasz Grzegorz Maciak
Version: 0.1
Author URI: http://terminally-incoherent.com/
*/ 
 
// plugin function
function test_wordfilter($text) 
{
 
	$words = array ( "foo " => "bar ",
				" test" => " done");
 
	foreach ($words as $key => $value)
	{
		$text = str_replace($key, $value, $text);
	}
 
 
	return $text;
}
 
// wordpress hook
add_filter('comment_text', 'test_wordfilter');
 
?>

I think the function is pretty straightforward – take a string, create array, loop through array, replace every $key with a corresponding $value, return a string. If you don’t get it, tough. Figure it out.

The line you want to pay attention to is this one:

add_filter('comment_text', 'test_wordfilter');

This is a wordpress hook. There are two types of hooks – actions and filters. Actions are triggered by various events such as publishing a post. Filters on the other hand let you manipulate the way data is displayed on the screen.The function add_filter takes two parameters.

The first parameter is the name of the filter. In our case it is comment_text because we only want to use our word filter in the comments. If we wanted to also apply this filter to blog posts we would need to add another filter like so:

add_filter('the_content', 'test_wordfilter');

You can find a full list of available filters and actions in the WordPress Plugin API Refference.

As you probably guessed, the second parameter is the name of the function you defined in the plugin. Note that your function name should be unique, not to collide with other plugins and native wordpress functions. Most filters will return some desired data and send it as a parameter to your function.

Note that this plugin includes a full comment block with all the attributes filled out. If you look at your plugin manager, here is how it will show up:

Plugin Manager with the Test Plugin
click to enlarge

Now all we have to do is to activate the plugin. If it works, it should tell you that activation was successful, and the entry should become green. If you have some errors in your script, you will get a brief error message. Usually it’s something among the lines of “unable to activate the plugin due to fatal error”. This makes debugging your plugins bit difficult, so it’s a good idea to use an editor which checks PHP syntax as you type, like for example Komodo Edit. This will cut down on the number of silly typos, and forgotten semicolons in your code.

Once the plugin is activated, pop over to our comments section we can see that it worked:

Filtered Comments

Note that this plugin is far from perfect. For example it changes the word foobar into barbar which might not exactly be what we wanted. It’s probably a good idea to change the str_replace fucntion to preg_replace and use regular expressions to ensure that only the words we want get replaced. But that’s something you can do on your own.

Now you have a fully functional plugin to play around with. How easy was that?

[tags]wordpress, wordpress plugins, plugin, php, blog[/tags]

This entry was posted in programming and tagged , , . Bookmark the permalink.



4 Responses to Writing Your First WordPress Plugin

  1. TeamCOltra UNITED STATES Mozilla Firefox Windows says:

    I am currently working on a WordPress Plugin site because all the current ones suck so this one is going to break the mold.

    Reply  |  Quote
  2. Pingback: Writing Your First Wordpress Plugin at Life of Coltra UNITED STATES WordPress

  3. Luke UNITED STATES Mozilla Firefox Ubuntu Linux says:

    [quote comment="5135"]I am currently working on a WordPress Plugin site because all the current ones suck so this one is going to break the mold.[/quote]

    Ah, cool! Are you going to aggregate links from all the other sites or make it submission only listing? Or both?

    Reply  |  Quote
  4. I am going to make it where people upload their plugins :D
    http://www.e107coders.org or http://plugins.e107.org kinda a mix of those two sites but for wordpress

    Reply  |  Quote

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>