How to Create a WordPress Plugin From Scratch (My Complete 2026 Process)

Never write your first plugin directly on a live site. Install WordPress locally so you can break things freely — and you will break things. Local by WP Engine takes about five minutes: download it, click "Create a new site," and you'll have a working WordPress install with admin access on your own machine.

Inside wp-content/plugins/, create a new folder. Name it exactly how you'll name your plugin — lowercase, hyphen-separated. I'll use my-first-plugin for this guide. Inside that folder, create one PHP file with the same name: my-first-plugin.php. That file is what WordPress will read.

my-first-plugin/
  my-first-plugin.php
  assets/
    style.css
    script.js
  readme.txt

This is the part beginners skip and then wonder why their plugin never shows up in the dashboard. The header is a PHP comment block at the very top of your main file. WordPress parses it to know your plugin's name, version, and author — without it, your file is just inert PHP that WordPress ignores completely.

<?php
/**
 * Plugin Name: My First Plugin
 * Plugin URI: https://growwp.in
 * Description: A simple starter plugin built step by step.
 * Version: 1.0.0
 * Author: Akash Vishwakarma
 * Author URI: https://growwp.in
 * License: GPL v2 or later
 * Text Domain: my-first-plugin
 */

// Block direct access to this file.
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

Log in to wp-admin → Plugins. You should see "My First Plugin" listed with the description and author you wrote in the header. Click Activate. If nothing shows up, double-check that your header comment block sits at the very top of the file with no stray characters before <?php.

This is where it stops being a blank file and becomes an actual plugin. WordPress runs on hooks: actions let you run code at a specific moment, and filters let you change data before WordPress uses it. Let's add a small credit line to the site footer using the wp_footer action.

<?php
function gwp_add_footer_credit() {
    echo '<p class="gwp-credit">This site runs My First Plugin.</p>';
}
add_action( 'wp_footer', 'gwp_add_footer_credit' );

Save, refresh your site's front end, and you'll see the line appear right before the closing </body> tag. Notice the function name starts with gwp_ — that prefix matters, and I'll explain why in the mistakes section below.

Shortcodes let users drop dynamic content into posts and pages using simple tags like [gwp_welcome]. They're one of the most common things clients ask for, so it's worth getting comfortable early.

<?php
function gwp_welcome_shortcode( $atts ) {
    $atts = shortcode_atts( array(
        'name' => 'Friend',
    ), $atts );

    return '<div class="gwp-welcome">Welcome, ' . esc_html( $atts['name'] ) . '!</div>';
}
add_shortcode( 'gwp_welcome', 'gwp_welcome_shortcode' );

Now typing [gwp_welcome name="Akash"] into any post outputs "Welcome, Akash!" Notice I used esc_html() around the attribute — never echo a value straight from user input without escaping it first.

Never link a stylesheet or script with a raw <link> or <script> tag in a plugin. Use wp_enqueue_scripts so WordPress can manage loading order, avoid duplicate files, and let other plugins play nicely with yours.

<?php
function gwp_enqueue_assets() {
    wp_enqueue_style(
        'gwp-style',
        plugin_dir_url( __FILE__ ) . 'assets/style.css',
        array(),
        '1.0.0'
    );

    wp_enqueue_script(
        'gwp-script',
        plugin_dir_url( __FILE__ ) . 'assets/script.js',
        array(),
        '1.0.0',
        true
    );
}
add_action( 'wp_enqueue_scripts', 'gwp_enqueue_assets' );

Most real plugins need at least one settings screen. Use add_options_page() to register the page and the WordPress Settings API to handle saving — it gives you nonce protection and sanitization callbacks for free.

<?php
function gwp_register_settings_page() {
    add_options_page(
        'My First Plugin Settings',
        'My First Plugin',
        'manage_options',
        'gwp-settings',
        'gwp_render_settings_page'
    );
}
add_action( 'admin_menu', 'gwp_register_settings_page' );

function gwp_render_settings_page() {
    ?>
    <div class="wrap">
        <h1>My First Plugin Settings</h1>
        <form method="post" action="options.php">
            <?php
            settings_fields( 'gwp_settings_group' );
            do_settings_sections( 'gwp-settings' );
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

This is the step that separates a plugin you can actually ship from one that gets flagged in a security review. Three habits, every single time: verify a nonce before processing a form, sanitize data coming in, and escape data going out.

<?php
if ( ! isset( $_POST['gwp_nonce'] ) || ! wp_verify_nonce( $_POST['gwp_nonce'], 'gwp_save_action' ) ) {
    wp_die( 'Security check failed.' );
}

// Sanitize incoming data.
$safe_input = sanitize_text_field( wp_unslash( $_POST['gwp_name'] ) );

// Escape on the way out.
echo '<p>Hello, ' . esc_html( $safe_input ) . '</p>';

Use these to set up anything your plugin needs on activation — like a default option — and clean it up on deactivation, so you don't leave orphaned data in the database.

<?php
function gwp_on_activate() {
    add_option( 'gwp_version', '1.0.0' );
}
register_activation_hook( __FILE__, 'gwp_on_activate' );

function gwp_on_deactivate() {
    delete_option( 'gwp_version' );
}
register_deactivation_hook( __FILE__, 'gwp_on_deactivate' );

Even if you only plan an English version today, wrapping visible text in translation functions costs nothing now and saves a full rewrite later. Use the Text Domain you set in your header.

<?php
echo esc_html__( 'Welcome to my plugin!', 'my-first-plugin' );

Stop guessing why something isn't working. Open wp-config.php on your local install and turn on debugging so PHP errors show up in a log file instead of silently failing or breaking the page.

<?php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

With this on, every error gets logged to wp-content/debug.log instead of showing on screen — readable for you, invisible to visitors. I keep this on for every local build, no exceptions.

Once it's tested, zip the entire plugin folder — not just the PHP file — keeping the folder structure intact. That zip is what you upload through wp-admin → Plugins → Add New → Upload Plugin on any other site, or what you submit to the WordPress.org Plugin Directory for review if you're releasing it publicly.

Before zipping, I always do one final pass: deactivate and reactivate the plugin on a clean install, check the browser console for JS errors, and read through debug.log one more time. Five minutes here has saved me from shipping broken plugins more than once.