Writing your first WordPress plugins


A WordPress plugin “extends” WordPress, adding new functionality to it. You might want your site to filter out spam comments, to provide a contact form, or even to add unicorns on top of your content when a user is inactive for too long. If you can write it in PHP, you can add it to WordPress. Writing custom plugins is an enormous topic, so this article will aim to get you started and connected with the right resources.

Setting up a dev environment

With so much power and flexibility you’re inevitably going to break things, and you’ll need to set up a WordPress instance locally on your own computer to develop on. One good way to do this is with free and cross-platform software called AMPPS. http://www.ampps.com/downloads AMPPS will set up an Apache server, a MySQL server, and PHP on your computer. Once it’s running, you can install WordPress by visiting “https://stackcodify.com/ampps/”. For the settings, leave the protocol and domain at their defaults, but set the directory, site name and description, and admin account information. When the installation is finished, you should see a wordpress site at https://stackcodify.com/the-directory-you-chose, just waiting to be tinkered with!

Next you’ll need to find the actual files that make up WordPress. These will vary from OS to OS, but AMPPS has a button to take you to your “Root Directory”, where you’ll see a folder the-directory-you-chose containing .php files. For development you’ll want to edit wp-config.php so that debug information gets saved to wp-content/debug.log:

 // find the WP_DEBUG value and change it to true:
 define( 'WP_DEBUG', true );
 // add these extra lines before “That’s all, stop editing!”
 define( 'WP_DEBUG_LOG', true );
 define( 'WP_DEBUG_DISPLAY', false ); 

Many of the files you’ll find in your WordPress directory are part of the “core”—Don’t edit them!—but WordPress knows to check the wp-content/plugins directory for additions, and in that folder you’ll find “hello.php”, a classic example plugin. Let’s take a look.

Hello Dolly

At the top you’ll see a specially formatted header:

Plugin Name: Hello Dolly

Plugin URI: http://wordpress.org/plugins/hello-dolly/

Description: This is not just a plugin, it symbolizes the hope and enthusiasm of an entire generation summed up in two words sung most famously by Louis Armstrong: Hello, Dolly. When activated you will randomly see a lyric from <cite>Hello, Dolly</cite> in the upper right of your admin screen on every page.

Author: Matt Mullenweg

Version: 1.7.2

Author URI: http://ma.tt/


There are two other important things to notice about the Hello Dolly plugin. You’ll see that it defines a few functions:

  • hello_dolly_get_lyric() returns a random line of lyrics from the song
  • hello_dolly() renders a line of lyrics as html, and prints it.
  • dolly_css() prints css that applies to the html from hello_dolly()

Those three functions tell WordPress how to display the lyrics, but it also needs to know when to display them, and to do this we use something called “hooks.” WordPress provides two types of hooks: “filters” which allow you to modify content before it’s displayed, and “actions” which allow you to change or add to normal WordPress functionality. In hello.php you’ll see two calls to “add_action”:

  • “add_action( ‘admin_notices’, ‘hello_dolly’ );” This uses the “admin_notices” hook to tell WordPress to call hello_dolly() when generating the notices section of the administration page.
  • “add_action( ‘admin_head’, ‘dolly_css’ );” WordPress will call dolly_css() when generating the header section of the administration page.

Creating a barebones plugin

The only header field that’s strictly required is “Plugin Name”. In fact, a single php file with a plugin name in the header comment is technically a full plugin! Create a file wp-content/plugins/empty-plugin.php, with the content:



Plugin Name: Empty Plugin


This is already a complete plugin. It doesn’t do anything, but you can activate and deactivate it at https://localhost/the-directory-you-chose/wp-admin/plugins.php. What next?

More resources

Check out WordPress’s header documentation for suggestions of other information you may want to provide about your plugin.

WordPress provides a massive number of hooks. To get an idea of what’s possible, you can browse their action reference and filter reference. Some of the most common ones are “register_activation_hook”, “register_deactivation_hook”, and “register_uninstall_hook” for customizing what happens when you activate, deactivate, and uninstall your plugin. 

WordPress also provides several APIs to help you do things like save settings, create admin widgets, or define “shortcodes” so that blog editors can make use of your plugin while creating content. Read more about what’s available here.

When your plugin grows in size, including Javascript files, CSS files, static images, and other PHP files, you’ll want to put it in its own folder. Refer to WordPress’s documentation for this and other best practices, and to Devin Vinson’s WordPress Plugin Boilerplate for a good example of plugin structure.

If you’re not careful, you can introduce security issues. See the WordPress documentation on checking user capabilities, data validation, and sanitizing input.

Since security is such a big risk, many WordPress hosts won’t allow you to install your own plugins. When you’re ready to deploy your plugin, you may need to purchase a more expensive plan from your provider. Alternatively, self-hosting in the cloud can give you much more control. Digital Ocean’s One-Click-Install tutorial is one example of how to do this.

Tim Clark

Tim Clark

Friendly Polyglot
Hello! I've used a lot of different technologies for work (Python/Django, PHP/Wordpress, git, SQL, AWS, HTML/CSS/Javascript) and constantly seek new programming experiences on my own, so I'm prepared to help with a wide variety of languages and topics.