Shortdark Software Development

How to write a WordPress Plugin

Development5th Oct 2016.Time to read: 9 mins

PHPPluginTutorialWordpress

There are 1,000s of WordPress Plugins and each one is individual, but for anyone wanting to make a plugin for themselves here are a few basics to help you get stated. I made my first plugin recently for WordPress and I was amazed at how little information was out there. So, I decided to make this simple tutorial on "How to write a WordPress Plugin" for anyone else with an interest in web programming or web design who would like to see if they can make a plugin. Obviously, the plugin itself will be whatever you want it to be and will be as complex as you want to make it. This tutorial will be an easy introduction that you can add to if you wish.

Prerequisites

While it can be very straight-forward there are two things you'll definitely need to begin working on a WordPress plugin.

  • A working version of WordPress whether on a website or on a localhost.
  • Knowledge of PHP.

You are going to need a working version of WordPress. I won't go into the details here of how to setup and install a WordPress blog but if you are interested in making a WordPress plugin I'm assuming that you've had some experience with using WordPress.

WordPress has many existing functions that will assist you in making your plugin but the programming language that you'll need to use to make a WordPress plugin is PHP. There's no getting around the fact that you should probably have some PHP knowledge to make a plugin that behaves exactly the way you'd like it to behave and has all the functionality you want it to have. I'd say that you may not have to be a PHP whizz and you can learn-as-you-go, but you'd need to have an understanding of programming languages, and an idea of how to write PHP.

A good source of information about PHP is PHP.net, often searching for a PHP function will take you there. Another good place for PHP examples and troubleshooting is Stack Overflow, again searching for a problem you are having will often take you here where someone has generally already asked the question and it has already been answered.

Why WordPress? Why a plugin?

WordPress rocks. There are many many people using WordPress all over the world, and WordPress.com is in the world's top 50 websites. The basic blogging software is amazing and constantly evolving, but the power of WordPress is in it's open source. Because the source code can be viewed by anyone and there is extensive online documentation many people have made plugins and themes which aid and enhance WordPress blogs. Through plugins you can modify almost any aspect of the blog, adding things, removing things and changing it until it is almost unrecognisable from the original blog you added to your hosting.

You'll want to use plugins that other people have made, but maybe the plugin that would be perfect for you has not been made yet. If this is the case or you just want to give it a try, read on...

Making a WordPress Plugin: First Things First

Ok then, let's begin! We'll start off with a one page plugin. The first thing you have to do is open up a text editor and create a file called whatever you'd like your plugin to be called. There are 1000's of plugins already so my advice would be to call it something with at least 2 or 3 words in the name if you wish to submit to the WordPress Repository. WordPress needs each plugin to have a unique filename so that there are no conflicts between different plugins. This concept extends to the naming of functions which should all begin with a unique prefix so as not to cause any conflicts with WordPress functions or functions of other plugins. If you are not interested in submitting your plugin you can call it pretty much whatever you like as it'll only be on your website.

So, let's call our plugin "My First Ever Plugin" and give it the filename "my-first-ever-plugin.php" and let's start off with this code in our PHP file, I'll call this the "header" code...

<?php
/**
 * @package my-first-ever-plugin
 * @version 0.0.01
 * Plugin Name: My First Ever Plugin
 * Plugin URI: https://shortdark.co.uk/2016-10-05-how-to-write-a-wordpress-plugin/
 * Description: My plugin does...
 * Author: My Name
 * Text Domain: my-first-ever-plugin
 * Version: 0.0.01
 * Author URI: https://shortdark.co.uk/
 */

It should be fairly self-explanatory. This plugin will have the file "my-first-ever-plugin.php" in a directory called "my-first-ever-plugin". If your plugin was called "Whatever" it would have a file called "whatever.php" inside a directory called "whatever". The description is a short description of what the plugin does.

Prevent Direct Access

Next, still on the "my-first-ever-plugin.php" file, it's good practice to prevent direct access to your plugin. I.e. we want the plugin to be used by someone within their WordPress blog, we do not want the plugin to be accessed from elsewhere. To prevent direct access we insert this code after the header...

/**************************
 ** PREVENT DIRECT ACCESS
 **************************/

defined('ABSPATH') or die('No script kiddies please!');

So, if "ABSPATH" is not defined the PHP script will die().

Believe it or not, we're almost done if you're just making a WordPress plugin for your own use. I'll cover the steps you need to take if you want to add your plugin to the WordPress repository later. All that has to be done now is to hook some code to WordPress.

Hook It Up

WordPress uses "hooks" to connect functions you have written to a WordPress blog. A hook can be either an "action" or a "filter". An action adds something and a filter changes something that already exists. We will use a filter for this tutorial but an example of an action would be to make a page in the admin area we would use the "add_action" like this... "add_action('admin_menu', 'function_name');". For more information check out the WordPress Plugin API reference.

Here we are filtering the content of all the posts and pages. We are going to add some "Hello World!" text in

tags at the end of the post and page content. We make a function that has the parameter "$content" then we hook the function using the filter "the_content" whoch means that whatever we return from the function will replace the post or page content. As we do not want to remove the content we just want to add to it I have just added the string we want onto the end of the "$content" variable.

This goes next in the "my-first-ever-plugin.php" file...

/**********************
 ** DO SOMETHING
 **********************/
// Add "<p>Hello World!</p>" to the end of each post and page
function mfep_hello_world($content) {
	$content .= "<p>Hello World!</p>";
	return $content;
}

// Hook the function to "the_content"...
add_filter('the_content', 'mfep_hello_world');

Notice, I have named my function beginning with an acronym of my plugin. My plugin is called "My First Ever Plugin" so I put "mfep_" at the start of all my function names.

And, that's it. You've made a plugin!

Make your WordPress Plugin Translatable

To make your plugin translatable you'll need to load your text domain. In the "header" we had a line like this...

 * Text Domain: my-first-ever-plugin

So, now we need to use another hook, which this time is an "add_action" to tell WordPress where you'll be storing the translation files. Here, I'm storing the translation files in a directory within my plugin called "languages".

/****************************
 ** LOAD PLUGIN TEXT DOMAIN
 ****************************/

function mfep_load_textdomain() {
	load_plugin_textdomain('my-first-ever-plugin', false, dirname(plugin_basename(__FILE__)) . '/languages');
}

add_action('init', 'mfep_load_textdomain');

Again, you'll notice that my function has the acronym of my plugin name, "mfep_", at the beginning.

That's all we have to do in the "my-first-ever-plugin.php" file.

readme.txt

If you want to submit your plugin to the WordPress repository you'll also need a "readme.txt" file in your plugin directory.

Similar to the header of the PHP file, the readme.txt also has a header...

=== My First Ever Plugin ===
Contributors: shortdark
Donate link: https://shortdark.co.uk/2016-10-05-how-to-write-a-wordpress-plugin/
Tags: posts, pages
Requires at least: 3.5
Tested up to: 4.6.1
Stable tag: trunk
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Adds a Hello World! to the end of the post and page content.

The plugin title is on the top line in between two sets of "===". Contributors is hwo has helped to make the plugin. Tags should be exactly the same as the ones that WordPress has already. You can see the existing tags here. Requires at least is the minimum WordPress version number your plugin should work for. Our plugin here is very simple but if you used a WordPress function that was created fairly recently you should investigate which version of WordPress it was introduced in. This will allow you to calculate the minimum version without installing every single version of WordPress ever. Tested up to should be the version of WordPress you have tested your plugin on. This should always be the latest version of WordPress because you should always update to the latest version every time an update comes out. Stable tag is telling WordPress which is the stable version of your plugin. To begin with this will be the "trunk". Then, your plugin must be open source and it must have a public licence, Lastly, before the next section of the "readme.txt" you can add one sentence to describe your plugin. This will be what will show up on the plugin page of the user's blog after they download your plugin.

The rest of readme.txt

After the one sentence short description you can add a much longer description that can be as long as you like with several paragraphs. Links can be added as shown with the link text in square brackets before the URL in brackets. Then comes the necessary "Installation" and "Changelog" sections. You'll notice that all the sub headings are in the middle of a set of "==" and the subheadings have "=" around them.

== Description ==

Much longer description goes here.

Please let me know if you like this plugin by leaving a review or [contacting me](https://shortdark.co.uk/contact/).

Go to the [Shortdark Wordpress plugin page](https://shortdark.co.uk/2016-10-05-how-to-write-a-wordpress-plugin/) for more information.

== Installation ==

This section describes how to install the plugin and get it working.

1. Upload the plugin folder to the `/wp-content/plugins/` directory, or install the plugin through the WordPress 
plugins screen directly.
2. Activate the plugin through the 'Plugins' screen in WordPress.

== Changelog ==

= 0.0.01 =

* New plugin.

That's it!

Once you've finished your readme.txt you can check your readme.txt at the readme.txt validator.

Now you're ready to review the Plugin Directory information zip your plugin up and submit it to the WordPress Repository.

Once your Plugin has been Approved

WordPress uses SVN, so you'll probably need something like TortoiseSVN to upload your plugin to the WordPress repository. More info on how to do that at this youtube video.

Here are some extra things that I didn't find out immediately that might be helpful to you.

Add images to your WordPress Plugin Page

You should have two images: "banner-772x250.jpg" and "icon-128x128.jpg". They can be in your plugin folder (the "trunk" of your WordPress repository), or it may be better to put them in your "assets" folder out of the way. These will be the banner image at the top of your plugin page and the square icon that people will see when they search for a plugin.

Add Screenshots

To add a screenshots section you simply add "== Screenshots ==" to your readme.txt.

== Screenshots ==

Here are some screenshots...

1. Nice screenshot of my plugin.
2. Another screenshot of my plugin.

Each number in this section will be a different screenshot. Screenshot 1 will look for the file "screenshot-1.jpg", and screenshot 2 will look for "screenshot-2.jpg". Similar to the banner and icon, you'll either put these images in your trunk or in your assets folder. The text by each number on the readme.txt is the caption that will go under the image on the screenshot page.

Everything All Together

The complete files from this "How to write a WordPress Plugin" tutorial can be cloned or downloaded from GitHub page.

Next: Setting up a Linux Webserver with SSH in 20 Steps (Debian 8)