This article will take you by the hand and lead you to become a WordPress plugin developer. We’ll analyze when the circumstances call for writing a plugin, where to place your plugin code and some best practices, and give you a taste of a few WordPress concepts regarding plugin development while coding a simple plugin.
So you’ve been developing themes, probably adding CSS and maybe some navbars or footer functions. How do you know when it’s time to take a leap into WordPress plugin development?
What is a WordPress Plugin?
A plugin is a piece of code that adds functionality to your site beyond what WordPress offers you at its core.
A plugin is a piece of code that adds functionality to your site beyond what WordPress offers you at its core. The code might alter the content of a post or add something to the site, or enable you to do things on the admin side of the site.
A plugin can add as little or as much functionality as needed: a small plugin can, for example, insert a Google Analytics script into your site or add a thumbnail to your posts, or send email notifications to commenters when their comment has been replied to. A medium-sized plugin might add an accessibility toolbar to your site, enable embedding PDF and WORD documents inside your post, or add a recommendation system to your site. Large plugins can add impressive functionality to the site, such as adding a forum system, adding numerous SEO enhancements, or turning the site into a store.
Plugins are built as folders containing at least one PHP file, inside
wp-content/plugins.
In its technical basics, a WordPress plugin is a folder that resides in your WordPress site’s wp-content/plugins folder. The folder contains, at the very least, a php file with code that influences the site’s functionality.
How to Become a WordPress Plugin Developer, in 4 Steps
Since a WordPress plugin can be and do just about anything, there’s no limit to how complex custom WordPress plugin development can be as a topic. However, getting started in custom plugin development is as simple as following the four steps below:
1. Make Sure You Need a Custom Plugin
So you’ve decided that your site needs some additional functionality. Does that automatically mean you should sit down and create a plugin? Not necessarily. Lots of functionality changes are best handled by modifying your WordPress theme, or are well covered by existing plugins.
You’ll want to ask both of these questions before you dive in:
Are Your Changes Data-Based, Or Purely Display-Based?
Even when we understand that touching core files is not an option, we still don’t necessarily have to place the code in a plugin. When the functionality you want to incorporate is tightly related to your site’s theme, adding it to the theme itself makes sense. The theme has a file dedicated to adding such code: the functions.php file. Features such as adding navigation bars, widget areas, translation files, support for featured images, etc., are a good fit for belonging in the functions.php.
However, if you want the functionality to stay even when changing a theme, you want that code to reside outside of the theme, and that’s where plugins come into play.
Is There an Existing Plugin that Does What You Want?
So we’ve determined that the code does belong in a plugin, but before we sit ourselves down and churn out code, let’s look first in WordPress’s Plugin Repository. The plugin repository has tens of thousands of plugins, spanning a multitude of categories: Form Generators, Security, Backup, Caching, Forums, E-Commerce, and many others. You can get an idea of many useful developer plugins from our tutorial videos. The plethora of existing WordPress plugins means that for most of what we want to add to the site there already exists a plugin.
So when would we choose to run a plugin of our own? When either no existing plugin does exactly what we want, or the plugins that do, are bloated and add more complexity than we would like.
Custom Plugin Time!
Okay, we’ve verified that we should be using a plugin, and that no existing plugin does what we want. Time for us to write a plugin!
What? Us? Write a plugin? But we’re we’ve never written one, we’ve barely written PHP—how can we leap into plugin development? That’s what we’re here for: taking a guided, step-by-step, plunge into the magical world of WordPress plugin development.
2. Create the Plugin Folder and File
We’ll start by creating enough of a plugin to enable you to see it in the plugins screen on your site. The plugin won’t do anything yet, but it will show up on the list of plugins on your site.
- FTP into your site’s file system
- Go to the
wp-contentfolder - Go into the
pluginsfolder - Create a folder and name it whatever your plugin is supposed to do. If it requires multiple words, put a hyphen between them. For example, if our plugin is displaying tag posts in reverse chronological order, let’s name the folder
display-tag-posts-reverse-order. - Create a PHP file and give it the same name you gave the folder (including the hyphens). In the above example:
display-tag-posts-reverse-order.php.wp-content/ | |- plugins | |- your-plugin-name/ | | |- your-plugin-name.php
3. Insert a Comment Header so the Plugin Appears in the Plugin List Screen
- Open the
phpfile and insert a comment header (similar to the comment header in the theme’s style.css). The minimum comment header can have only one field—the plugin name—but we’ll add a few more fields so it shows up like all other plugins:<?php /** * Plugin Name: YOUR PLUGIN NAME * Description: A DESCRIPTION OF THE PLUGIN'S FUNCTIONALITY * Author: YOUR NAME * Version: 1.0 */Note: Remember the opening PHP tag at the beginning of the file. Without it, WordPress won’t recognize the comment header.
- A full header comment could consist of all these fields (you can read up on each field’s definition in wordpress.org’s Plugin Development Handbook): Plugin Name, Plugin URI, Description, Version, Requires at least, Requires PHP, Author, Author URI, License, License URI, Text Domain, Domain Path, Network.
Now go to your site’s plugin screen, and—voila—your plugin is there!
Now let’s put some code in that plugin so your plugin actually does something…
4. Write the Actual Plugin PHP
If you’re not familiar or comfortable with PHP, this stage might be what has kept you from writing a plugin till now. Our free course on PHP for WordPress can help with that:
In any case, fear not: even without mastering PHP you can start writing your first plugin.
When looking to add specific functionality to a site, I typically start with a web search. The search will usually lead to some code that implements my needs. And while it’s important to understand what the code does and how it works, you’re still exempt from having to write the code all on your own.
We’ll write a simple plugin that affects specific tag archive pages, causing them to display posts in reverse chronological order.
In this section, we’ll write a simple plugin that affects the archive pages of particular tags that we specify, and causes their posts to be listed in reverse chronological order. While doing that, we’ll learn about prefixing function names, using hooks, getting acquainted with the query parameters, and other methodologies that I’ve learned from the best WordPress plugin developers.
Prefix Function Names
When writing a plugin that’s not encapsulated in a namespace or a class, the plugin functions become part of WordPress’s global scope. That means that they’re in scope with many many other functions, whose names we do not know. Not knowing other function names could result in us giving our function a name that already exists, which would mean that either that function would override ours or ours would override it. Neither of those is the desired outcome, and therefore we must give our functions unique names. The easiest way to do that is by prefixing each function name with a variation of our plugin name.
If our plugin name is short, such as my-plugin, our functions can be called my-plugin-get-posts or my-plugin-enqueue-scripts. However, we do not want long function names, so if our plugin has a long name, we can abbreviate it. For example, if our plugin is called display-tag-posts-reverse-order, we can abbreviate it to dtpro and call our functions dtpro-get-posts or dtpro-enqueue-scripts.
Another solution is to use namespaces. While I’d like to go into that too, I also want to keep this article short and basic, therefore I’ll just refer you to a more in-depth article about namespaces in WordPress:
Hooks
Hooks are our plugin’s way of tapping into the WordPress workflow at given points in the code’s execution. If we just write a function that gets the posts in reverse chronological order, how will WordPress know that our code exists? Wha’s going to make the site stop and say: wait, there’s this plugin code that has to run now?
That’s where hooks come into action. WordPress’s code has many junctions in which it stops and says: “Here I want to run all the code that wants to tap into my workflow at this point”. In the immortal words of Jan Fabry, a WPSE top user:
“WordPress hooks work like Hollywood: you don’t call them, they call you. But unlike Hollywood, they keep calling everyone on the list.”
So in our code, we define the point to which we want to hook, and what function we want WordPress to run then. In order to understand the code we use to define that, we’ll just explain that there are two kinds of hooks: action hooks and filter hooks. Explaining them is beyond the scope of this article, so I recommend that you read WPShout’s in-depth article about them.
WordPress Hooks, Actions, and Filters: What They Do and How They Work
For our purposes, it’s enough if we way that the hook we’ll be using is an action hook, and we’ll be hooking into the pre_get_posts action. As explained in the excellent article Practical Uses of pre_get_posts, “pre_get_posts is an action that lets you modify a WP_Query that is “about to run,” meaning “about to ask the database for a post bundle.” Before the query can run off to the database and get its bundle of posts, we’re going to swoop in and change which posts the query will actually request. This order of events is how pre_get_posts gets its name.”
Since we want to change the order in which posts are fetched from the database in some tags, this is the ideal code point for us to tap in and insert our modifications.
Conditional Tags
So we got WordPress to run our code every time it accesses the database. But we don’t want to change the order of posts on the whole site, only in those tags pages.
How do we do that? We tell WordPress to modify the query only under certain conditions: That we’re in a tag page, that we’re in a particular tag, and that the query running is the main one (because there are several more queries running on each page: for the navigation bar, or a sidebar, etc.)
WP_Query Parameter
The query that fetches posts from the database, using the WP_Query class, has many parameters by which to fetch posts: by author, category, by status or by date, and many more. In our case, there is only one thing we want to change: the order in which the posts are retrieved. So we’re just going to set that parameter, and send the query on its way.
A Sample Plugin’s PHP Code
After all that explaining, here is the full code. You just insert it in your plugin file after the comment header, change the tag slug to suit your needs, and use it to your heart’s content.
add_action( 'pre_get_posts', 'dtpro_get_posts' );
/**
* For only the 'mooc' tag, show the posts in ascending date order, so they can be read from beginning to end
*/
function dtpro_get_posts( $query ) {
if ( $query->is_tag() && ( $query->query_vars['tag']=='mooc' ) && $query->is_main_query() ) {
$query->set( 'order', 'ASC' );
}
}That Sample Plugin’s Full Code, With Comment Header
Here is the full code, top-to-bottom, of the main PHP file that would create this plugin:
<?php
/**
* Plugin Name: Display Tag Posts Reverse Order
* Description: Reverse chronological ordering for specific tag archive pages
* Author: WPShout
* Version: 1.0
*/
add_action( 'pre_get_posts', 'dtpro_get_posts' );
/**
* For only the 'mooc' tag, show the posts in ascending date order, so they can be read from beginning to end
*/
function dtpro_get_posts( $query ) {
if ( $query->is_tag() && ( $query->query_vars['tag']=='mooc' ) && $query->is_main_query() ) {
$query->set( 'order', 'ASC' );
}
}Drop that into a new folder (named anything, but naming it dtpro would probably make sense) inside /wp-content/plugins would make this plugin and its functionality available within the WordPress admin. Give it a try!
Where to Go From Here
In this post, we’ve learned how to write our first plugin, and you should officially consider yourself a WordPress Plugin Developer after achieving that!
There are, of course, many paths in which you can navigate from here: you can dive into any or all of the posts linked to from this article; you can read our step-by-step tutorial on writing a WordPress plugin from scratch; you can delve into wordpress.org’s Plugin Developer Handbook, or you can take our full WordPress development course, Up and Running, which teaches WordPress plugin development—and all of WordPress development—clearly and in-depth.
Whatever path you take, whether you follow the footsteps of others or pave your own path, good luck and enjoy your journey!
