Tag: Web Development

How To Write Your First WordPress Plugin

After you have been using WordPress for some time, I bet you have some slight modifications you want to make. Maybe changing the title of a specific archive from “Category: Favorites” to “My Favorite Posts”?

I’m going to walk you through the basics of how to write your first plugin so you can modify your site or write a plugin to help out others who may not want to get involved with code.

Basic File Structure

Every WordPress plugin starts out with at least one file. It handles all the functionality required and controls the files that are included. This file should be named similar to what you’re calling your plugin, but it does not necessarily have to match word for word. (an example would be Hello Dolly and hello.php–see? Similar)

When WordPress boots up, it loads it’s core files first, then starts to walk through the plugin list. It includes each plugin in sequence until it reaches the end. This is where your plugin gets included and adds functionality by running code contained in this main plugin file.

Note: This is why you get the “White Screen Of Death” with WordPress. When there’s an error, processing the code stops and you’re left with a white screen.

The Plugin Header

Within the main plugin file, WordPress looks for a specific PHP comment that defines the information needed to show the plugin in the backend. It looks a little something like this (which you can find in the WordPress documentation by the way):

<?php
/**
 * Plugin Name: WordPress.org Plugin
 * Plugin URI:  https://example.com/plugins/the-basics/
 * Description: Basic WordPress Plugin Header Comment
 * Version:     20160911
 * Author:      WordPress.org
 * Author URI:  https://author.example.com/
 * License:     GPL2
 * License URI: https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: wporg
 * Domain Path: /languages
 */

Each line references a different aspect of the plugin:

  • Plugin Name: What are you calling this plugin?
  • Plugin URI: this link is where you will send users when they click on the plugin “visit site” in the plugin screen of the admin
  • Description: What does your plugin do for the user?
  • Version: What version is your plugin? Usually, when first starting the plugin, you’ll want to set this to version “1.0”
  • Author: Your Name
  • Author URI: Just like the Plugin URI, where should users be sent when they click on your name? Your website perhaps?
  • Text Domain: This is a setting that WordPress uses for Internationalization (or I18n as you may have seen ), but we won’t be using that and you can just leave it out for now.
  • License: This ( & License URI) you can grab from the WordPress docs as all plugins have to be compatible with WordPress’ licensing.

Main Plugin File

This is the file that you’re going to be writing the “meat” of your plugin. It’s essentially your entry point into the WordPress lifecycle.

If your plugin is adding some simple functionality it might fit all in this single file, however, if you have more than about 100 lines, I’d consider breaking it up into separate files and including them. Breaking up the code into multiple included files helps with maintenance and readability.

Probably one of the biggest concepts to understand when writing a plugin is how the code is run. In PHP, you have functions that contain a section of code that runs whenever you call it. In WordPress, you have specific helper functions called actions and filters.

These actions and filters are hooks into the WordPress loading cycle so you can have functions run at specific times in the cycle. Also, actions can be seen as something that does something, and filters are filtering something.

For example, let’s say that you wanted to send an email every time WordPress loads before it does anything else (this is a terrible idea, it should never be done). You would write the function to send the email (wordpress_loaded()) then you would use the add_action function to call your function.

// Define our function to run when WordPress loads.
function wordpress_loaded() {
   wp_mail( user@email.com, "WordPress Loaded!" );
}

// Add the hook to call our function when WordPress begins to load.
add_action('init', 'wordpress_loaded');

Also, if you wanted to change one of your act archive page titles, you would use the add filter function, grab one of the parameters and do any checks to make sure you’re on the right page, then return what the title needs to be.

function rename_archive_title( $title ) {
    if ( is_archive('posts') ) {
        return "My New Archive Title";
    }
    return $title;
}

add_filter( 'get_the_archive_title', 'rename_archive_title' );

Activation & Deactivation Hooks

Since you now know about add_action and add_filter, WordPress includes some addiotional hooks like activation and deactivation. These run any time a user activates or deactivates your plugin on their site.

Typically people use these to clean up anything the plugin is using.

Plugins can use things like transients and custom database tables that might be left behind after the plugin has been removed. Although, not everything should be removed on deactivation. You want all the users’ settings to stay, but you want some data to be cleaned up.

WordPress also has an uninstall hook that you can use to remove everything that the plugin would leave behind. These hooks are great to set up in the beginning and you just keep adding to them as your plugin grows. Everything you create that could get left behind, should be added to this uninstall hook.

Installation & Testing

Once you have finished programming your plugin and need it to actually run on a WordPress site for testing, all you have to do is package up the file into a .zip. If you’re on a Mac, control-click and select compress. on a pc …. something.

You can then upload this zip to your WordPress site and activate it. Although I would highly recommend testing it locally before uploading it to your live site as it could cause some headaches if you didn’t double check your code first.

To Sum Up

You should now understand how WordPress loads plugins, how to write a basic plugin, add functionality to WordPress and some best practices for cleaning up after your plugin.

Let me know if you got some value out of this in the comments. I’d love to hear about your plugins that you’re building!

More Resources