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 Write a WordPress Plugin: A Beginner's First Plugin

How to Write a WordPress Plugin: A Beginner's First Plugin

Short answer

To write a WordPress plugin, create a folder in wp-content/plugins, add a PHP file with a header comment containing at least Plugin Name, and activate it under Plugins. Then add your features with WordPress hooks, using actions to run code at set moments and filters to change data. Prefix your function names and sanitize input and escape output.

Key takeaways

  • A plugin is a PHP file with a header comment, placed in its own folder under wp-content/plugins.
  • Hooks are the core idea: actions run your code, filters change data.
  • Prefix function names or use classes to avoid clashes with other plugins.
  • Sanitize input, escape output and check permissions and nonces for security.
  • Test on a local or staging site, and use the Plugin Check tool before publishing.

What is a WordPress plugin?

A plugin is a package of PHP code, and sometimes CSS, JavaScript and images, that adds features to WordPress without changing core files, so your changes survive updates and can be switched on or off.

The official Plugin Handbook is the main reference for plugin development. It covers everything from the basic file structure to security and publishing.

If you only need a small tweak, such as one snippet, a code snippet plugin may be simpler. Our guide on adding code to WordPress compares that route with writing a full plugin.

What do you need before you start?

You need basic PHP knowledge, a code editor, and a local or staging WordPress site where mistakes cannot affect real visitors.

If your PHP is rusty, the official PHP manual is the best reference for functions and syntax.

Never develop on a live site. One syntax error can take the whole site down. Our guide on setting up a local WordPress development environment shows how to create a safe place to work.

Turn on debugging while you develop by setting WP_DEBUG to true in wp-config.php. Errors and warnings then appear, which helps you catch problems early.

How do you create the plugin folder and main file?

Create a folder in wp-content/plugins with a unique name, such as my-first-plugin, and inside it create a PHP file with the same name, such as my-first-plugin.php.

The folder name becomes your plugin's slug, so make it unique and descriptive. Use lowercase letters and hyphens.

Keep the main file small. As the plugin grows, move code into separate files in an includes folder and load them from the main file.

What goes in the plugin header?

The main file must start with a PHP comment block containing at least a Plugin Name line; other common lines include Description, Version, Author, License, Requires at least and Requires PHP.

<?php
/**
 * Plugin Name: My First Plugin
 * Description: Adds a short note after every post.
 * Version: 1.0.0
 * Author: Your Name
 * License: GPL-2.0-or-later
 * Text Domain: my-first-plugin
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

The header requirements page lists every supported field. Once the header is saved, the plugin appears under Plugins in the dashboard, ready to activate.

The ABSPATH check stops anyone from running the file directly from the browser. It is a small, standard safety step.

How do hooks work?

Hooks let your code run at specific points in WordPress: actions run your function when something happens, such as a post being saved, and filters let you change data, such as post content, before it is used.

This is the most important idea in plugin development. Instead of editing core files, you attach your functions to hooks WordPress already provides.

For example, the the_content filter receives a post's content and returns it. Your function can add a note to the end and return the changed version:

function mfp_add_note( $content ) {
    if ( is_singular( 'post' ) ) {
        $content .= '<p class="mfp-note">' . esc_html__( 'Thanks for reading!', 'my-first-plugin' ) . '</p>';
    }
    return $content;
}
add_filter( 'the_content', 'mfp_add_note' );

The Plugin Handbook's hooks chapter explains actions, filters and priorities in depth.

Why should you prefix everything?

All plugins share one PHP environment, so a generic function name like add_note can clash with another plugin and cause a fatal error; a unique prefix such as mfp_ avoids that.

Apply the prefix to functions, global variables, option names, custom post types and CSS classes. Alternatively, wrap your code in a class or a PHP namespace.

Pick a prefix of at least four or five characters that relates to your plugin name. Very short prefixes are more likely to collide, and generic ones like wp_ belong to WordPress itself.

How do you add a settings page?

Use the admin_menu action to add a page under Settings, and the Settings API to register, display and save options securely, rather than handling form data by hand.

The Settings API handles nonces and saving for you, which removes a common source of bugs and security holes. You register a setting, add sections and fields, and WordPress builds the form.

Store options with a prefixed name, and delete them when the plugin is uninstalled, so you do not leave clutter behind.

How do you keep a plugin secure?

Sanitize all input, escape all output, check user capabilities before doing anything sensitive, and use nonces to confirm that form submissions and actions really came from your site.

Sanitizing cleans data coming in, for example with sanitize_text_field. Escaping makes data safe to print, for example with esc_html or esc_url. Do both, even for data you think is safe.

Capability checks, such as current_user_can, make sure only the right users can change settings. Nonces protect against requests forged from other websites.

The Plugin Handbook's security section covers each of these with examples. Most plugin vulnerabilities come from skipping one of them.

How do you handle activation, deactivation and uninstall?

Use register_activation_hook to set up things like default options, register_deactivation_hook to pause scheduled tasks, and an uninstall.php file to remove the plugin's data when someone deletes it.

Deactivation should not delete data, because users often deactivate plugins temporarily while troubleshooting. Save cleanup for uninstall.

In uninstall.php, check that the WP_UNINSTALL_PLUGIN constant is defined before deleting anything. That confirms WordPress itself called the file as part of a real uninstall, not someone loading it directly.

If your plugin adds custom post types or rewrite rules, flush rewrite rules on activation, so new URLs work straight away.

How do you make a plugin translatable?

Wrap visible text in translation functions such as __ and esc_html__ with your text domain, so translators can create versions of your plugin in other languages.

The text domain should match your plugin slug. Plugins hosted on WordPress.org can be translated by volunteers through the community translation platform.

Even if you only plan to use English, writing translatable strings from the start costs little and makes the plugin easier to share later. Adding translation calls to an existing plugin afterwards means hunting through every file for visible text, which is slow and easy to get wrong.

How do you load CSS and JavaScript in a plugin?

Register and load files with wp_enqueue_style and wp_enqueue_script inside the wp_enqueue_scripts action for the front end, or admin_enqueue_scripts for the dashboard, instead of printing script tags by hand.

Enqueueing lets WordPress manage dependencies, avoid loading the same library twice and let caching plugins optimise your files. Use plugins_url or plugin_dir_url to build the correct file address.

Load assets only where they are needed. If your plugin's styles apply only to single posts, check is_singular before enqueueing, so other pages stay lighter.

Write modern, accessible front-end code. The MDN Web Docs are a reliable reference for JavaScript, and they note browser support for each feature.

How do you keep track of changes to your plugin?

Use a version control system such as Git from the first day, commit small changes with clear messages, and bump the Version line in the plugin header for each release.

Version control lets you see exactly what changed between releases and roll back a mistake in seconds. It also makes collaboration and code review much easier.

Keep a simple changelog in your readme file too. Users and site owners want to know what each update changes before they install it.

How do you test and share your plugin?

Test with debugging on, try it with a default theme and with common plugins, then run the Plugin Check tool before zipping the folder or submitting it to the WordPress.org plugin directory.

The Plugin Check plugin scans your code for common problems and for issues the directory reviewers look for. Fix everything it flags before submitting.

To share privately, zip the plugin folder. Anyone can install it under Plugins > Add New Plugin > Upload Plugin.

Plugins in the official directory must use a GPL-compatible licence. Our explainer on what the GPL means in WordPress covers what that involves.

Frequently asked questions

What is the minimum code for a WordPress plugin?

A single PHP file in its own folder under the plugins directory, starting with a comment block that includes a Plugin Name line. WordPress then lists it on the Plugins screen, where you can activate it.

Do I need to know PHP to write a plugin?

Yes, at least the basics. Plugins are mainly written in PHP, often with some JavaScript and CSS. Learning how WordPress hooks work is just as important as general PHP knowledge.

What is the difference between an action and a filter?

An action runs your function at a certain moment, such as when a post is saved. A filter passes data to your function, which must return it, possibly changed, such as edited post content.

Can I put my plugin code in functions.php instead?

You can, but code in a theme's functions file stops working when you change themes. A plugin keeps the feature independent of the theme, which is better for site functionality.

How do I publish a plugin on WordPress.org?

Prepare a readme file, check your code with the Plugin Check tool, make sure it uses a GPL-compatible licence, then submit it through the plugin directory's add page for review.

Sources

  1. Plugin Handbook WordPress Developer Resources
  2. Header Requirements WordPress Developer Resources
  3. Hooks WordPress Developer Resources
  4. Plugin Security WordPress Developer Resources
  5. Plugin Check WordPress.org Plugins
  6. PHP Manual php.net
  7. JavaScript MDN Web Docs

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

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.