Writing a Simple WordPress Plugin, Beginner Tutorial

A WordPress Plugin is a program, or a set of one or more functions, written in the PHP scripting language, that adds a specific set of features or services to the WordPress weblog, which can be seamlessly integrated with the weblog using access points and methods provided by the WordPress Plugin Application Program Interface (API). – Writing a Plugin, WordPress Codex

In layman’s language, a WordPress plugin is a simple program that helps you to customize and enhance your WordPress website without having to edit the core programming. When you master WordPress plugin development, you will be able to add all manner of functionality to your WordPress blog in no time. But before you become a pro, you must learn the ropes.

In today’s post, we will guide you through the process of creating your first WordPress plugin. We will keep the tutorial simple to cater for the first time developer who has little to no knowledge of PHP (the scripting language behind WordPress).

Before getting down to actual coding, however, we will look at a few things you ought to understand about WordPress plugin development.

Basics To Know Before Creating a WordPress Plugin

In this section, we will reveal the first few steps you need to follow when creating a WordPress plugin. In addition, we will mention all the various things you need to put into consideration as you write your plugin. Great. Let’s start with the basics.

How to Name A WordPress Plugin

Before everything else, you need to come up with a unique name for your WordPress plugin. One of the best ways to determine a favorable name is to think of what your plugin will do. So, for instance, if your plugin will help people share content via social media, you can include the phrase “social media sharing” in the name. Another thing, plugin names can be several words, so don’t mince creativity.

Your plugin name must be unique to avoid conflicts with other plugins. To ensure your name is unique, you can do a Google search on the name. Additionally, you can search the various plugin directories including the WordPress plugin repository.

To name any plugin, we have to create at least one plugin file (the main PHP file), which introduces us to our next section.

How to Create Plugin Files

A plugin can be made up of a single PHP file or multiple files depending on what it’s designed to do. The most important file is the main PHP file, which is the equivalent of index.php and index.html in WordPress themes and HTML designs respectively.

It’s recommended that WordPress developers name their main plugin file after their plugin by convention. For instance, the main plugin file for a plugin called WP Renym plugin would be wp-renym.php. If adding a separator in your name, only use hyphens ( – ) between words as opposed to underscores ( _ ).

As mentioned above, a plugin can be made of a single or multiple files (images, JavaScript, language, CSS files etc). Either way, your plugin files must live in a single directory. So for a plugins named WP Renym the wp-renym.php file would be placed in a wp-renym folder. Additional sub folders can be added inside the main plugin folder to contain and organize other files.

After you lay down all the code for a plugin you then compress your main folder into a zip file (in this case it would be wp-renym.zip archive) to be uploaded and installed on a WordPress site.

Adding a File Header to the Main PHP file

When naming your plugin you should add other details such as description, version, license, author name – basically everything that will appear under and alongside your plugin in the WordPress Plugins Screen – the the plugin header. For this you must use a standard plugin information header at the top of your main PHP file. This is how a typical header looks:


/*
Plugin Name: Name of your plugin
Plugin URI:  http://link to your plugin homepage
Description: Describe what your plugin is all about in a few short sentences
Version:     1.0
Author:      Your name (Yay! Here comes fame... )
Author URI:  http://link to your website
License:     GPL2 etc
License URI: http://link to your plugin license
*/

Every parameter in the header above is self explanatory so I won’t go into the details. Just ensure you include the relevant http:// or https:// when writing your Plugin and Author URIs or the links won’t work.

Follow your header with the following license information if you’ll use a GPL2 license or a license compatible with the GPL2:

/* Copyright YEAR PLUGIN_AUTHOR_NAME (email : your email address)
(Plugin Name) is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
any later version.
 
(Plugin Name) is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
 
You should have received a copy of the GNU General Public License
along with (Plugin Name). If not, see (http://link to your plugin license).
*/

The scope of this tutorial does not allow us to go beyond these basic steps. You will need to check out the writing a plugin guide in the codex to learn more about WordPress plugin hooks, template tags, saving plugin data to databases, plugin options mechanism and updating your plugin among other things. The codex also includes a massive Plugin Resources collection that is full of video guides, advanced topics and more.

Now that we’ve covered the basics, let’s write a simple WordPress plugin that will perform two basic (but nifty) functions:

  • Replace words in your content with your own choice of words
  • Add a “Thank you for reading this tutorial…” note at the end of every blog post.

How to Write a Simple WordPress Plugin – WP Renym

In this section, we will write code for the WP Renym plugin I’ve been mentioning all along.

What you need:

Naming Our Plugin

First, we checked the WordPress plugin repository and did a Google search on our name; WP Renym was free. My initial choice was WP Rename but it was already taken.

Moving on… Open a new file in your code editor, and add the following code at the top after opening your plugin with <?php:

/*
Plugin Name: WP Renym
Plugin URI:  http://link to your plugin homepage
Description: This plugin replaces words with your own choice of words.
Version:     1.0
Author:      Freddy Muriuki
Author URI:  http://link to your website
License:     GPL2 etc
License URI: https://link to your plugin license

Copyright YEAR PLUGIN_AUTHOR_NAME (email : your email address)
(Plugin Name) is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
any later version.
 
(Plugin Name) is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
 
You should have received a copy of the GNU General Public License
along with (Plugin Name). If not, see (http://link to your plugin license).
*/

Save the file as wp-renym.php in the wp-renym folder. If you don’t have the folder already, create it. wp-renym.php will be your main PHP file.

Adding Functions

Now to add the actual functions to the plugin. Just below the code above, add the following function to correct misspellings of wordpress to WordPress:

function renym_wordpress_typo_fix( $text ) {
	return str_replace( 'wordpress', 'WordPress', $text );
}
add_filter( 'the_content', 'renym_wordpress_typo_fix' );

renym_wordpress_typo_fix is the unique name we’ve given our function. When adding new functions never start them with wp_ – this to prevent any future incompatibilities with WordPress code functions which all use the prefix wp_.

Our PHP function takes ( $text ) as the argument, and returns the 1st string ‘wordpress’ replaced with the 2nd string ‘WordPress’.

We’ve added a filter ( add_filter ) to our plugin to tell our function ( renym_wordpress_typo_fix ) to work on the text we’ve selected, which in this case is the entire post content ( the_content ).

To replace more than one word (perhaps you would like to edit multiple words across your blog or use the plugin as a simple profanity filter), replace the above code with the following code:

function renym_content_replace( $content ) {
	$search  = array( 'wordpress', 'goat', 'Easter', '70', 'sensational' );
	$replace = array( 'WordPress', 'coffee', 'Easter holidays', 'seventy', 'extraordinary' );
	return str_replace( $search, $replace, $content );
}
add_filter( 'the_content', 'renym_content_replace' );

In our code above, we’ve already selected the words to replace e.g. wordpress, goat, Easter, etc. We’ve also selected the replacement words e.g. WordPress, coffee, Easter holidays etc. Hopefully the code is somewhat self explanatory:

  • The renym_content_replace function takes ( $content ) as the argument, replaces all the words contained in the $search array and returns the now-modified words to WordPress.
  • $search contains all the words to be replaced
  • $replace contains the replacement words
  • str_replace does what it does best, replacing words with the new words

Note how we add the prefix renym to every function. This prevents conflicts with other plugins that might be installed. You should get into the habit of adding prefixes to your functions whether you’re developing plugins, themes or widgets.

If you’ve completed the above steps your plugin can replace all your selected words effectively. Now let’s add the “Thank you for reading this tutorial …” note that will appear at the bottom of every post. Add the following code to your main plugin file ( renym_content_replace ) before the closing PHP bracket ( ?> )  that comes in the last line:

function renym_content_footer_note( $content ) {
	$content .= '<footer class="renym-content-footer">Thank you for reading this tutorial. Maybe next time I will let you buy me a coffee! For more WordPress tutorials visit our <a href="http://wpexplorer.com/blog" title="WPExplorer Blog">Blog</a></footer>';
	return $content;
}
add_filter( 'the_content', 'renym_content_footer_note' );

Save the changes. The renym_content_footer_note function adds the HTML markup to the $content parameter and returns the new value to WordPress. We’ve also added a footer class to our text so it can be easily styled later on.

We’ve included a filter ( add_filter ) which tells our function to operate on the text we’ve selected, which is the post content as represented by the_content.

Compress Your Folder

At this point, your final wp-renym.php file should look like this:

<?php
/*
Plugin Name: WP Renym
Plugin URI:  http://link to your plugin homepage
Description: This plugin replaces words with your own choice of words.
Version:     1.0
Author:      Freddy Muriuki
Author URI:  http://link to your website
License:     GPL2 etc
License URI: https://link to your plugin license

Copyright YEAR PLUGIN_AUTHOR_NAME (email : your email address)
(Plugin Name) is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
any later version.
 
(Plugin Name) is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
 
You should have received a copy of the GNU General Public License
along with (Plugin Name). If not, see (http://link to your plugin license).
*/

/*Use this function to replace a single word*/
function renym_wordpress_typo_fix( $text ) {
	return str_replace( 'wordpress', 'WordPress', $text );
}
add_filter( 'the_content', 'renym_wordpress_typo_fix' );

/*Or use this function to replace multiple words or phrases at once*/
function renym_content_replace( $content ) {
	$search  = array( 'wordpress', 'goat', 'Easter', '70', 'sensational' );
	$replace = array( 'WordPress', 'coffee', 'Easter holidays', 'seventy', 'extraordinary' );
	return str_replace( $search, $replace, $content );
}
add_filter( 'the_content', 'renym_content_replace' );

/*Use this function to add a note at the end of your content*/
function renym_content_footer_note( $content ) {
	$content .= '<footer class="renym-content-footer">Thank you for reading this tutorial. Maybe next time I will let you buy me a coffee! For more WordPress tutorials visit our <a href="http://wpexplorer.com/blog" title="WPExplorer Blog">Blog</a></footer>';
	return $content;
}
add_filter( 'the_content', 'renym_content_footer_note' );

?>

Save all your changes. Compress the WP Renym folder into a wp-renym.zip archive (on a Mac it’s as easy as right click, compress file – and on PC I beleive it’s very similar). Just make sure your file saves as a .ZIP extension or the plugin won’t install.

Use Your Plugin

Upload and activate your new WP Renym plugin via the WordPress Plugins Screen. Congrats on writing your first plugin!

Install the Renym WordPress Plugin

Resources

To learn more above WordPress plugin development, please check out the following resources:

Conclusion

I hope this tutorial pointed you in the right direction as far as understanding plugins go. This post should serve as a stepping stone to developing complex WordPress plugins that do whatever you will. Don’t stop here, check out the resources I recommended above to increase your knowledge of WordPress plugin development.

If you found this tutorial helpful or if you have anything else to add we’d love to know. Please share your thoughts in the comments section below. See you around 🙂

Freddy
Post Author: Freddy

Freddy is a WordPress theme reviewer at WP Theme Raves, published WordPress blogger, web dev and founder of Vista Media Enterprises, an online business dedicated to WordPress users looking to boost conversion rates via content marketing.

Disclosure: This page contains external affiliate links that may result in us receiving a comission if you choose to purchase said product. The opinions on this page are our own. We do not receive payment for positive reviews.
Got something to say? Join the discussion.
  1. Nice article, with the help of this article we can understand the basic of plugin development.
  2. Aakanksha says:
    Great tutorial, with all the basic things covered in depth. If you could do a full start to finish tutorial of a plugin that would be nice (just a suggestion). Theme Creator (thetechpower.com)
  3. aleksandarpetrovicsp says:
    Best tutorial!
  4. That is one of the best writing sample about WordPress plugin. I would like to congratulate you for great contribution. I also would like to say that from your content people might get better Idea. Thanks to share with us for your great job.
  5. Jigar Shah says:
    Wow... What a perfect source to learn WP Plugin Development..! I know the value of this post because of I am also WP Plugin developer and I also wrote an article guide about WordPress Plugin Development. I hope you will like it and please let me know your reviews and thoughts about it. Once again thank you for the best WP tutorial.
  6. Matthew Arias says:
    Thanks for sharing good article because as a newbie it is hard to understand WP plugin development. In this post, you shared your knowledge in simple way. I'm glad to learn from Freddy.
    • Freddy
      Thanks for the kind words Matthew, we are glad the post was useful. Cheers!
      Author

Leave a Reply