How to Create a WordPress Plugin
If you’ve been building your own themes for a while, chances are you’ve been adding code to the functions.php file. Sometimes you might have wondered if you should be writing a plugin instead, but you weren’t sure how.
In many cases, writing a plugin is better practice than adding code to your functions.php file. And creating a plugin is far simpler than you might think.
In this post, I’ll show you how to create a plugin, and identify when it’s better to write a plugin instead of adding code to your theme. I’ll also give you some techniques and code to help you activate the code on your plugin, including functions, action and filter hooks, shortcodes and widgets.
When Should You Write a Plugin?
There are times when writing a plugin is best, and times when you can just add the code to your theme’s functions file:
Use functions.php when you need to add simple functionality related to the way your content is displayed (i.e. it won’t work without your theme activated). This might include adding extra fonts, for example.
Write a plugin when the functionality is more complex or when the extra functionality isn’t dependant on the theme. An example is registering post types – you don’t want to lose your post types if you change themes in the future.
What Techniques Are Involved in Writing Plugins?
To write a plugin you’ll need to create the plugin file and add code to it which you then activate in one way or another. Every plugin has some opening code which is commented out (I’ll show you this shortly), followed by the plugin code. If your plugin gets large or you want to keep elements of it separate, you’ll need to create include files – extra PHP files that you call in your main plugin file. I’ll show you how to do this later in this post. You might also want to include stylesheets and scripts in your plugin, in which case you enqueue them. Again I’ll show you this later in the post.
There are a few ways for the code in your plugin to be activated:
Via a function
Your plugin creates a function which you then add to your theme somewhere to call the code inside the function.
Via an action hook
WordPress includes hundreds of action hooks you can use to call the code in the functions you write in your plugin. If your theme (or another plugin you’ve activated on your site) has an action hook, you can write a function which you then attach to that hook instead. The code in your plugin will then run when WordPress loads that hook.
Via a filter hook
Again, WordPress provides plenty of filter hooks which let you change what’s output. A filter hook is different from an action hook in that it lets you change code that’s already output, instead of adding new code. You might also find filter hooks in your theme or other plugins that you can use to activate the code in your own plugin.
Via a shortcode
Your plugin can create a shortcode that you then add to your posts or pages.
Via a widget
If your plugin creates a widget, you activate that by adding it to a widget area in the WordPress admin screens.
In this post, I’ll show you how to create your plugin and also how to do some of these things, with code examples.
Opening the Plugin
To create a plugin, you simply create a file in your
wp-content/plugins directory with the following opening code:
You’ll need to edit the code above with your own details, but you can see it’s very simple.
Once you’ve saved your plugin, it will appear in the Plugins admin screen where you can activate it:
So that’s all you need to do to create a plugin. Next you’ll need to add some code to it. Let’s take a look at the different ways of activating code in a plugin.
Writing Functions in Your Plugin
The most basic thing you can do in a plugin is write a function. You can then output that function using a hook or by typing the function name into your theme.
So let’s say you want to create a function for a call to action button, and then add it in multiple places in your theme.
The function for your button would look something like this:
Above I’ve used
echo to echo out HTML inside my PHP function. If you’ll be adding a lot of HTML inside your function and don’t want to use
echo so much, you can add closing and opening PHP tags inside your function instead:
Now when you want to add your call to action button to your site, you just add the function in the relevant places in your theme template files, like so:
This is much more efficient than adding that code to your theme every time you want a call to action button – there’s less code for WordPress to run and less for you to maintain.
Activating Your Function via a Hook
There’s an alternative to typing your function into your theme template files every time you want the function to fire. If your theme has hooks (which will certainly be the case if you’re using a theme framework), you can hook your function to one or more of those hooks instead. Or you can use one of the hooks provided by WordPress or by a plugin you’ve already activated.
So if your theme has an action hook in the sidebar called
mytheme_sidebar, you can hook your function to it using the
add_action() function has two mandatory parameters: the hook you’re attaching your function to, and the name of your function. There’s also a third optional parameter, which is the priority with which you want to fire your function. Use this if you want to make sure one function is run before or after another.
You can attach your function to as many hooks as you want. So if you wanted to add your call to action button in the sidebar and below the content in your theme, using a
mytheme_below_content hook, your plugin would look like this:
If you want to hook your code to one of the action hooks provided by WordPress, you do it in exactly the same way. An example is creating a plugin that adds Google analytics tracking code to your site, and hooks it to the
Attaching code via a filter hook works in just the same way, except you use the
add_filter() function instead. So if the content of the call to action box has already been added to the theme using a filter, you can override it like this:
Writing a Plugin for a Shortcode
If your plugin creates a shortcode, you don’t run the code it provides using a hook or by adding the function to your theme template files. Instead, you type the shortcode into the content of your posts.
So if I wanted to create a shortcode for my call to action button I’d write this function in my plugin:
This includes the code we already added to our function, with the
ob_get_clean() functions. These ensure that the HTML in your shortcode is output at the place in the content that you add it; without these, it will be displayed at the top of the screen.
The function is activated via the
add_shortcode() function, which is part of the Shortcodes API. The function has two parameters: the first is the text users will need to enclose in square brackets to run the shortcode, and the second is the name of your function. So to add the call to action button in the content of your site, type [CTA].
Writing a Plugin for a Widget
The final way to activate the code in your plugin in your site is via a widget, which you add to your chosen widget area. Creating a plugin for a widget makes use of the Widgets API.
Creating a widget is more advanced so I recommend this tutorial to learn how to create the widget and the widget settings that your users can edit when they’re adding a widget to a widget area.
Now let’s move on from activation of your plugin code to see how you include files in your plugin.
Including Files in a Plugin
If your plugin requires assets such as stylesheets and scripts, or it’s larger and you want to split your code up into manageable chunks, it makes sense to use include files. In this case, you’d put your main plugin file in a folder in your
wp-content/plugins directory, instead of putting the plugin file straight into the directory. Your plugin file will look just the same and WordPress will still find it if it’s in its own folder.
My plugins often have one or more of these folders inside the plugin folder:
Including PHP Files
To include an extra PHP file in your plugin, add this code at the beginning of your plugin, after the opening commented out text but before your first function:
This will pull in the code from your include file in the place in your plugin where you’ve added that function. I tend to include all my files at the beginning of my plugin file, before any other functions. In some plugins, you might keep all of your code in include files and just add those
include_once functions to the main file.
To call a stylesheet in your plugin you need to enqueue it correctly instead of just including it. So if your call to action plugin had a stylesheet which added styling for that call to action button, you’d add it to your plugin file like this:
If you place this code in the main plugin file it will call a stylesheet called
style.css that’s in the
wp-content/plugins/myplugin/styles folder. It may feel odd that you’re hooking your function to an action called
enqueue_scripts, but that is correct for stylesheets as well as scripts.
You call scripts in a similar way to stylesheets, using the
enqueue_scripts hook. So if I wanted to add a script to animate my call to action button, I’d call it in my plugin like this:
This is very similar to the function we already used for stylesheets, but in the
I hope that this post has convinced you that writing plugins really isn’t as hard as you might think, and encouraged you to write your own. Using a plugin instead of adding code to the
functions.php file in your theme will help you to keep code that isn’t theme-dependant separate, and it also gives you code you can use again and again on different sites.
What was the first plugin you built? Do you have ideas for plugins you want to create? Tell us in the comments below.