Creating A WordPress Plugin

Table of Contents

Create first plugin in five simple steps

I’m not kidding. You can create a WordPress plugin in five simple steps. Let me show you how…

1. Navigate to the WordPress plugins folder

Once you’ve accessed your site via FTP, you’ll need to navigate to the WordPress plugins folder. That folder is almost always located at /wp-content/plugins.

2. Create a new folder for your plugin

Now that you’re in the plugins folder it’s time to create a folder for yours! Go ahead and create a new folder, giving it a unique name using lowercase letters and dashes such as my-first-plugin. Once you’ve done that, enter your new folder and move on to the next step.

3. Create the main PHP file for your plugin

Next, you’ll need to create the main file for your plugin. To do so, create a PHP file within your new plugin folder and give it the same name such as my-first-plugin.php. After you’ve done that, open your plugin’s main file and get ready to do some editing.

4. Setup your plugin’s information

Finally, copy and paste the plugin information below into your main plugin file. Make sure to edit the details such Plugin Name and Plugin URI as they pertain to your plugin.

<?php
 
/**
 
 * @package Akismet
 
 */
 
/*
 
Plugin Name: Akismet Anti-Spam
 
Plugin URI: https://akismet.com/
 
Description: Used by millions, Akismet is quite possibly the best way in the world to <strong>protect your blog from spam</strong>. It keeps your site protected even while you sleep. To get started: activate the Akismet plugin and then go to your Akismet Settings page to set up your API key.
 
Version: 4.1.7
 
Author: Automattic
 
Author URI: https://automattic.com/wordpress-plugins/
 
License: GPLv2 or later
 
Text Domain: akismet
 
*/

This tells WordPress what your plugin does, where to find out more about it, and who developed it. It also gives information about the version number and the text domain and path for internationalisation, as well as the license.

That’s it! You’ve just completed the minimum number of steps that are required to create a WordPress plugin. You can now activate it within the WordPress admin and revel in all of your glory.

At this point you’re probably wondering what this plugin is supposed to do. Well, it doesn’t do anything! I said I would show you how to create a plugin, I didn’t say I’d show you how to create a plugin that does anything.

All kidding aside, the goal of this post is to illustrate just how simple it is to get started creating WordPress plugins. Whip one up with the steps outline above and you’re ready to start making things happen.

Making your plugin do something simple

Now that you have a plugin, lets make it do something.

The easiest way to make things happen in WordPress is with actions and filters. Let’s explore that by creating a simple action that adds a line of text below all of the posts on your site. Copy and paste this code into your main plugin file (below the plugin information) and save it.

add_action( 'the_content', 'my_thank_you_text' );

function my_thank_you_text ( $content ) {
    return $content .= '<p>Thank you for reading!</p>';
}

This code hooks into “the_content” action that fires when WordPress renders the post content for your site. When that action fires, WordPress will call our “my_thank_you_text” function that is defined below the “add_action” call.

If you’ve made it this far, hopefully we’re in agreement that creating a simple WordPress plugin is relatively easy. But what if you want to create a plugin that does more than accomplish one simple task?

Folder Structure

While there are no hard and fast rules on how you organize the folders in your plugin, it makes sense to adopt the same structure that other plugin developers use. This will familiarize you with the way other plugins are built and mean that if you share your code in future, it will make sense to other people.

Folders in your plugin might include:

css or styles for stylesheets
scripts for JavaScript
includes for include files
templates for template files that your plugin outputs
assets for media and other asset files
i18n for internationalization files

You might find you need to use more folders if your plugin is large or complex. For example, WooCommerce has folders for packages, sample data, and more. These in turn include subfolders for things like blocks and admin files.

Scripts and Stylesheets

If your plugin outputs content that needs styling, either in the front-end or in the admin screens, you may need stylesheets. And if your plugin will use scripts, you’ll need files for these.

It makes sense to keep these in their own folder, even if you only have one of each. You’ll need to enqueue these scripts and stylesheets using a dedicated function in your main plugin file. I’ll show you how to do this when we’re building the plugin.

Include Files

If your plugin needs organisation, you can do this by splitting your code into multiple files, called include files. You then put these files into their own folder and call them in your main plugin file using an include or require function.

This way, you can keep the bulk of your code in a well-organised file structure while your main plugin file remains lean and minimal.

If your plugin isn’t all that big, you don’t need to use include files: just add your code to the main plugin file. But you might find you need to organise this file and reorder functions within it as you add them, to maintain a logical structure.

These are the most common elements of a plugin. We’ve seen in the WooCommerce example that there can be many more. Or in smaller plugins there can be many fewer. But as you develop more plugins, you’ll find yourself using these elements more and more.

How to Run Your Plugin Code: Options

When you add code to your plugin, it won’t do anything until you activate it in some way. There are a few methods you can use to activate your code or pull in code from WordPress:

functions
action and filter hooks
classes

Let’s take a look at each of these.

Functions

Functions are the building blocks of WordPress code. They’re the easiest way to get started writing your own plugins and the quickest to code. You’ll find plenty of them in your themes’ files too.

Each function will have its own name, followed by braces and the code inside those braces.

The code inside your plugin won’t run unless you call the function somehow. The simplest (but least flexible) way to do that is by directly calling the code in your theme or somewhere else in your plugin.

Here’s an example function:

tutsplus_myfunction {
 
// code goes here
 
}

To directly call that function in your theme, you’d simply type tutsplus_myfunction() in the place in your theme template files where you want it to run. Or you might add it somewhere in your plugin… but you’d also need to activate the code that calls it!

There are a few limitations to this:

If the function does something that isn’t just adding content somewhere in a theme template file, you can’t activate it this way.
If you want to call the function in multiple places, you’ll have to call it again and again.
It can be hard to keep track of all the places you’ve manually called a function.

It’s much better practice to call functions by attaching them to a hook.

Action and Filter Hooks

By attaching your function to a hook, you run its code whenever that hook is fired. There are two types of hook: action hooks and filter hooks.

Action hooks are empty. When WordPress comes to them, it does nothing unless a function has been hooked to that hook.

Filter hooks contain code that will run unless there is a function hooked to that hook. If there is a function, it’ll run the code in that function instead. This means you can add default code to your plugin but override it in another plugin, or you can write a function that overrides the default code that’s attached to a filter hook in WordPress itself.

Hooks are fired in three ways:

By WordPress itself. The WordPress core code includes hundreds of hooks that fire at different times. Which one you hook your function to will depend on what your function does and when you want its code to run. You can find a list of WordPress hooks in the developer handbook.
By your theme. Many themes include action and filter hooks that you can use to add extra content in key places in your website’s design. And all themes will include a wp_head and wp_footer hook. Combine these with conditional tags, and you can run specific code on certain types of pages in your site.
By your plugin or other plugins. You might add an action hook to your plugin and then add functions in your include files that attach code to that hook. Or you might write a filter hook and then have a function that overrides its contents under certain circumstances. Alternatively, if you’re creating a plugin to complement another plugin, you can hook your functions to the existing hook in the third-party plugin. I’ve done this with WooCommerce, for example, to customise what’s output on product pages.

Some of this is more advanced, but with your first plugin, you’ll probably be hooking your functions to an action or filter hook output by WordPress itself, most likely an action hook.

Classes

Classes are a way of coding more complex features, such as widgets and customizer elements, that make use of the existing WordPress APIs.

When you write a class in your plugin, you’ll probably be extending an existing class that’s coded into WordPress. This way, you can make use of the code provided by the class and tweak it to make it your own. An example would be the customizer, where you might write a class including a color picker, making use of the color picker UI that’s provided in the existing class for the customizer.

Using classes is more advanced than functions, and it’s unlikely you’ll do it in your first plugin. To find out more, see our guide to classes in WordPress.

If you do write classes, you’ll still have to use actions or filters to get them to run.