Skip to content

How to build your first WordPress plugin

The basics of a WordPress plugin: where it lives, the header WordPress needs, hooks, and the common mistakes to avoid.

A WordPress plugin is code that adds or changes features on a WordPress site. This guide explains the basic parts, using WordPress's official Plugin Handbook as the source. It does not teach PHP; it shows how a plugin is put together.

A plugin can be one file

A plugin can be a single PHP file placed in the plugins folder. More often, a plugin has its own folder, named after the plugin, with several files inside. WordPress scans the plugins folder and its subfolders to find plugins (Plugin Basics).

The header comment

WordPress recognises a plugin by a comment at the top of one PHP file. At a minimum it must contain the Plugin Name. Other optional fields include Version, Author and License (Header Requirements).

<?php
/**
 * Plugin Name: My First Plugin
 * Description: Adds a short note to the footer.
 * Version: 0.1.0
 */

If your plugin has several PHP files, only one of them should have this header comment.

Hooks: actions and filters

Plugins add their features by using hooks. The Plugin API calls them actions and filters (Plugin API Hooks). An action lets your code run at a certain moment. A filter lets your code change a value before WordPress uses it.

A tiny example that runs on the standard wp_footer action:

add_action( 'wp_footer', function () {
    echo '<p>Hello from my plugin.</p>';
} );

Activation and deactivation

If you need to do something when the plugin is switched on or off, you register activation and deactivation hooks. The first argument must be the path of the main plugin file, the one with the header comment (Activation / Deactivation Hooks).

A mistake to avoid: fixed paths

Do not assume your plugin lives in wp-content/plugins. Users can rename or move the wp-content folder. Use WordPress functions such as plugins_url() to build paths and URLs (Determining Plugin and Content Directories).

Add a license

If you plan to share or sell the plugin, include a software license. The handbook explains how (Including a Software License).

Make it translatable from day one

If your plugin shows text to users, prepare it for translation. The handbook has a guide: How to Internationalize Your Plugin. See also our guide on translating a WordPress site.

Next steps

Start with a very small plugin, test it on a copy of a site, and add features one by one. If you would rather have it built for you, we build custom WordPress plugins, from small features to full products. You can build a price estimate or send us a brief. Consultation is free.

Sources

Share this post