Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

How to Create a Simple WordPress Plugin

How to Create a Simple WordPress Plugin

Short answer

To create a simple WordPress plugin, make a folder in wp-content/plugins, add a main PHP file with the same slug, and put a header comment at the top with at least the Plugin Name. Add your feature with an action or filter hook, then open Plugins in the dashboard and activate it. Use the activation, deactivation, and uninstall hooks to set up and clean up the plugin data.

Key takeaways

  • A plugin is a PHP file with a header comment, held in its own folder in wp-content/plugins.
  • Only the Plugin Name header field is required; the description should stay under 140 characters.
  • Actions add or change WordPress behavior, while filters alter content as it is shown.
  • The activation hook sets up defaults, the deactivation hook clears short-lived data, and uninstall deletes plugin data.
  • Clean input early, check it against a set pattern, and escape it before you show it.

What is a WordPress plugin?

A WordPress plugin is a PHP file with a plugin header comment, held in its own folder, that adds a feature to your site.

At its simplest, a plugin is one PHP file with a header comment. Developer.WordPress.org states that it is highly recommended to create a directory to hold your plugin, so all of its files stay neatly organized in one place (checked November 2026).

Learn WordPress states that the minimum requirements for a valid plugin are at least one PHP file, the main plugin file, with an opening PHP tag and a plugin header that names the plugin (checked November 2026).

WordPress finds plugins by scanning the plugins folder for PHP files with header comments. Developer.WordPress.org states that when WordPress loads the Plugins page, it searches the plugins folder and its subfolders for PHP files with WordPress plugin header comments (checked November 2026).

A guide on theme vs plugin in WordPress explains the split: a plugin adds a feature that should keep working when the theme changes.

What do you need before you start?

You need a local WordPress site, a code editor, basic PHP, and one clear job for the first version of the plugin.

Pick one narrow job for version 1, such as adding a line of text to each post. A small first version is easier to build, to check, and to fix than a plugin that tries to do five things at once.

Check the PHP version your site runs. WordPress.org states that WordPress recommends PHP 8.3 or greater, and that WordPress still works with PHP 7.4 and later in older setups (checked November 2026).

Decide the plugin name, folder name, and a short prefix for your functions. The folder and main file usually share the plugin slug, such as my-basics-plugin for a plugin called My Basics Plugin.

A guide on free vs premium WordPress plugins explains the difference between plugins you download and plugins you build yourself.

How do you create the plugin folder and file?

Create a folder in wp-content/plugins, then add a main PHP file inside it with the same slug as the folder.

The handbook lists five steps: open the wp-content folder, open the plugins folder, create a new folder named after the plugin, open that folder, and create a new PHP file named after the plugin. Developer.WordPress.org gives the example of a folder and file both named plugin-name (checked November 2026).

From the command line, the same steps look like this:

cd wp-content
cd plugins
mkdir plugin-name
cd plugin-name

A plugin of one PHP file can sit directly in the plugins folder. Developer.WordPress.org states that a single-file plugin, like Hello Dolly, could sit in the root of the plugins folder, though most plugin files live in their own folder (checked November 2026).

Name the folder and file with lowercase letters and hyphens. A clear slug makes the plugin easy to find later, and it matches the text domain you will use for translations.

What goes in the plugin header?

The plugin header is a comment block at the top of the main file that names the plugin and states its version and requirements.

Only the Plugin Name field is required. Developer.WordPress.org states that at a minimum, a header comment must contain the Plugin Name, which is the name shown in the Plugins list in the dashboard (checked November 2026).

Header fieldWhat it statesRequired
Plugin NameName shown in the Plugins listYes
DescriptionShort summary of what the plugin doesNo
VersionCurrent version number, such as 1.0.3No
Requires at leastLowest WordPress version it works onNo
Requires PHPLowest PHP version it works onNo
AuthorName of the plugin authorNo
LicenseShort license name, such as GPLv2No
Text DomainText domain used for translationsNo
Domain PathFolder where translations liveNo

Keep the description short. Developer.WordPress.org states that the description should stay under 140 characters (checked November 2026).

Only one file in the plugin folder should carry the header comment. Developer.WordPress.org states that if the plugin has more than one PHP file, only one of those files should have the header comment (checked November 2026).

Version numbers follow PHP version_compare rules. Developer.WordPress.org states that WordPress uses the PHP version_compare function to compare plugin versions, and that 1.02 counts as greater than 1.1 (checked November 2026).

How do you add your first feature with hooks?

Connect your code to WordPress with an action or a filter, so it runs at the right point without editing core files.

WordPress hooks let you tap into WordPress at set points. Developer.WordPress.org states that actions let you add or change WordPress functions, while filters let you alter content as it is loaded and shown to the visitor (checked November 2026).

A filter example adds a short note to the end of each post:

function my_basics_plugin_add_note( $content ) {
    return $content . ' Note added by My Basics Plugin.';
}
add_filter( 'the_content', 'my_basics_plugin_add_note' );

Prefix every function with your plugin slug. A function named add_note could clash with another plugin, while my_basics_plugin_add_note is tied to your plugin alone.

Use the Options API to store settings in the database, and the HTTP API when your plugin needs to call an outside service. Developer.WordPress.org states that the Options API makes it easy to store data for your plugin, and that the HTTP API covers calls to outside services (checked November 2026).

How do you activate the plugin and check it works?

Save the file, open Plugins in the dashboard, and activate your plugin from the list.

After you save the main file, log in to the dashboard and open Plugins. Developer.WordPress.org states that your new plugin should now be in that list, ready to activate (checked November 2026).

Click Activate under your plugin name. Then open a post on the front end and check that your feature shows up as you expect.

If the plugin does not appear in the list, check three things: the file sits in wp-content/plugins, the header comment is at the top of the main file, and the Plugin Name line is present.

A guide on how to check a plugin for vulnerabilities covers how to review a plugin before you trust it on a live site.

How do you handle activation, deactivation, and uninstall?

Use the three lifecycle hooks to set up defaults on activation, clear short-lived data on deactivation, and delete plugin data on uninstall.

The three basic hooks are register_activation_hook, register_deactivation_hook, and register_uninstall_hook. Developer.WordPress.org states that these are the three basic hooks you will need when creating a plugin (checked November 2026).

The activation hook runs when the plugin is activated. Developer.WordPress.org states that you would use it to set up the plugin, for example by creating default settings in the options table (checked November 2026).

The deactivation hook runs when the plugin is deactivated. Developer.WordPress.org states that you would use it to clear any short-lived data stored by the plugin (checked November 2026).

The uninstall methods run when the plugin is deleted from the dashboard. Developer.WordPress.org states that you would use them to delete all data created by the plugin, such as options added to the options table (checked November 2026).

Put the rewrite flush or default setup in the activation hook, not in code that runs on every page load. That keeps the plugin light on each request.

How do you keep the plugin safe?

Treat all incoming data as untrusted, clean it before you use it, check it against a set pattern, and escape it before you show it.

Learn WordPress states that you should not trust any data, whether it is user input, third-party API data, or even data in your database, and that you should always check that it is valid and safe to use (checked November 2026).

Clean input as early as you can. Learn WordPress states that WordPress offers a cleaning API, and that you can use sanitize_text_field and sanitize_email to clean name and email fields before they are used (checked November 2026).

Check data against a set pattern before you act on it. Learn WordPress states that validating data means checking it against a set pattern with a clear result of valid or invalid (checked November 2026).

Developer.WordPress.org hosts the full security handbook for plugin and theme code, with the cleaning, checking, and escaping functions in one place (checked November 2026).

A guide on how to find abandoned WordPress plugins explains why a plugin with no updates is a risk, which is a good reason to keep your own plugin updated too.

What mistakes should you avoid?

Avoid a missing header, a generic function name, code that runs on every load, and a license that blocks sharing.

A plugin with no Plugin Name line will not appear in the Plugins list at all. Add the header first, before you write any feature code.

Generic function names clash with other plugins. Prefix every function, class, and option name with your plugin slug, and do not use wp_ as your own prefix.

Do not put setup work in code that runs on every page load. Developer.WordPress.org states that the activation hook is the place for setup, and it recommends checking your work often as you build (checked November 2026).

Pick a license that works with the GPL. Developer.WordPress.org states that to stay compatible with WordPress core, you should pick a license that works with the GNU General Public License, version 2 or later (checked November 2026).

GNU.org hosts the full text of the GPL version 2 license, which the header example links as its License URI (checked November 2026).

A guide on what the WordPress plugin review process covers explains what WordPress.org checks before a plugin is listed in the directory.

Frequently asked questions

Does a plugin need more than one file?

No. A plugin needs only one PHP file with a header comment that names it. A folder is strongly recommended so the files stay organized, but a single-file plugin can sit directly in the plugins folder. Add more files only when the plugin grows.

Which plugin header fields are required?

Only the Plugin Name field is required. A full header also lists a description under 140 characters, a version, the lowest WordPress and PHP versions it needs, an author, a license, and a text domain for translations.

What is the difference between an action and a filter?

Yes. Actions let you add or change what WordPress does at a set point, while filters let you change content as it is loaded and shown. A filter on the_content, for example, can add a line to the end of each post without editing any core file.

Why does my plugin not appear in the Plugins list?

Check that the file sits in wp-content/plugins, that the header comment is at the top of the main file, and that the Plugin Name line is present. WordPress only lists files it can read a header from, so a missing or misplaced header hides the plugin.

Can I release my plugin under the GPL license?

Yes, and it is the recommended license for sharing. WordPress core uses the GNU General Public License, version 2 or later, and the handbook recommends picking a license that works with it so your plugin stays compatible with core.

Can I add more features to the plugin later?

Yes. You can add a settings page, a shortcode, a widget, a custom post type, or a REST API endpoint to the same plugin. Keep each feature in its own file or function, prefix everything with your plugin slug, and check the plugin after each addition.

Sources

  1. Plugin Basics WordPress Developer Resources
  2. Header Requirements WordPress Developer Resources
  3. Plugin requirements Learn WordPress
  4. Securely developing plugins and themes Learn WordPress
  5. Security handbook WordPress Developer Resources
  6. Requirements WordPress.org

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test