How to Build a Custom WordPress Plugin from Scratch

Building a custom WordPress plugin from scratch is the cleanest way to add your own functionality without editing theme files or losing your changes on the next update. A plugin is simply a PHP file (or folder of files) that WordPress loads and runs using a system of hooks. If you can write basic PHP, you can build a plugin. This step-by-step guide walks you through creating a working WordPress plugin from an empty folder to an activated, functional plugin — complete with hooks, a shortcode, and the security best practices the pros follow.

Key takeaways

• A WordPress plugin needs just one PHP file with a valid plugin header comment to be recognized.
• Hooks — actions and filters — are how your plugin interacts with WordPress without touching core files.
• Always prefix your functions and block direct file access to avoid conflicts and security holes.
• Sanitize input and escape output — this is the single most important habit for safe plugin development.
• Put plugin logic in a plugin, not in your theme's functions.php, so it survives theme changes.

What you need before you start

• A local or staging WordPress install (never build on a live site).
• A code editor such as VS Code.
• Basic knowledge of PHP — variables, functions, and arrays.
• Access to your site's /wp-content/plugins/ directory.

Tip: Use a local environment like LocalWP, XAMPP, or Laragon so you can break things freely and iterate fast.

Step 1: Create your plugin folder and main file

Every plugin lives inside its own folder in wp-content/plugins/. Create a folder and a matching PHP file inside it:

wp-content/plugins/
  my-first-plugin/
    my-first-plugin.php

Using a folder (rather than a single loose file) keeps things organized and gives you room to add CSS, JavaScript, and extra PHP files later.

Step 2: Add the plugin header

WordPress only recognizes your file as a plugin if it has a special comment block at the top called the plugin header. Open my-first-plugin.php and add this:

<?php
/**
 * Plugin Name: My First Plugin
 * Description: A custom plugin built from scratch.
 * Version:     1.0.0
 * Author:      Your Name
 * License:     GPL-2.0+
 * Text Domain: my-first-plugin
 */

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

The Plugin Name line is the only required field — but filling in the rest is good practice. The ABSPATH check is a security must: it stops anyone from running the file directly in a browser.

Step 3: Activate your plugin

Log in to your WordPress dashboard, go to Plugins → Installed Plugins, find "My First Plugin," and click Activate. That's it — your plugin is now live and running, even though it doesn't do anything yet. If it appears in the list, your header is correct.

Step 4: Understand hooks — actions and filters

Hooks are the heart of WordPress plugin development. They let your code "hook into" specific moments without editing core files. There are two types:

• Actions — let you run your own code at a certain point (e.g. when the footer loads or a post is saved).
• Filters — let you modify data before WordPress uses it (e.g. change the post title or content).

Rule of thumb: use an action when you want to do something, and a filter when you want to change something.

Step 5: Add functionality with an action hook

Let's make the plugin actually do something. This example uses the wp_footer action to add a line of text to the bottom of every page:

add_action( 'wp_footer', 'myplugin_footer_note' );

function myplugin_footer_note() {
    echo '<p style="text-align:center">Powered by my first custom plugin.</p>';
}

Notice the myplugin_ prefix on the function name. Always prefix your functions with something unique to your plugin so they never collide with WordPress core, your theme, or other plugins.

Step 6: Create a shortcode

Shortcodes let users drop your feature into any post or page with a simple tag like [greeting]. Register one with add_shortcode():

add_shortcode( 'greeting', 'myplugin_greeting' );

function myplugin_greeting( $atts ) {
    $atts = shortcode_atts(
        array( 'name' => 'there' ),
        $atts
    );

    return 'Hello, ' . esc_html( $atts['name'] ) . '!';
}

Now typing [greeting name="Ibrahim"] in the editor outputs "Hello, Ibrahim!". A shortcode function must return its output, not echo it. Note the esc_html() — that escapes the output so user input can't inject malicious code.

Step 7: Load CSS and JavaScript the right way

Never hard-code <script> or <link> tags. WordPress has a proper system — enqueueing — that prevents duplicate and conflicting files:

add_action( 'wp_enqueue_scripts', 'myplugin_assets' );

function myplugin_assets() {
    wp_enqueue_style(
        'myplugin-style',
        plugin_dir_url( __FILE__ ) . 'css/style.css',
        array(),
        '1.0.0'
    );
}

Use plugin_dir_url( __FILE__ ) to build the correct path to your plugin's files — never hard-code the URL, or your plugin will break on other sites.

Step 8: Follow security and quality best practices

The difference between an amateur plugin and a professional one is discipline. Before you ship, make sure you:

• Prefix everything — function names, option keys, and constants — to avoid conflicts.
• Sanitize input, escape output — use functions like sanitize_text_field() on data coming in and esc_html() / esc_attr() on data going out.
• Use nonces to verify form submissions and protect against CSRF attacks.
• Check user capabilities with current_user_can() before running admin actions.
• Block direct access with the ABSPATH check in every PHP file.

How to test and debug your plugin

Turn on WordPress debugging so you catch errors early. In wp-config.php, set:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );

Errors will be written to wp-content/debug.log. Test your plugin with a default theme active and other plugins deactivated to confirm your code — not a conflict — is the cause of any issue.

Frequently asked questions

Do I need to know PHP to build a WordPress plugin?

Yes, at least the basics. WordPress plugins are written in PHP, so you need to understand variables, functions, and arrays. You don't need to be an expert — you can build a simple, useful plugin with fundamental PHP knowledge and a grasp of WordPress hooks.

What is the minimum needed to create a WordPress plugin?

The absolute minimum is a single PHP file containing a valid plugin header comment with a Plugin Name line, placed in the wp-content/plugins/ directory. Once WordPress detects that header, the plugin appears in your dashboard and can be activated.

Why build a plugin instead of editing functions.php?

Code in your theme's functions.php is lost when you switch or update the theme. A plugin keeps your custom functionality independent of the theme, so it keeps working no matter which theme is active — making it portable, reusable, and safer.

What are hooks in WordPress?

Hooks are points in WordPress where you can attach your own code. Actions let you run code at a specific moment, and filters let you modify data before it is used or displayed. They are the core mechanism that lets plugins extend WordPress without editing core files.

Final thoughts

Building a custom WordPress plugin from scratch comes down to four ideas: a folder with a main file, a valid plugin header, hooks to connect your code to WordPress, and disciplined security. Start small — a footer note or a shortcode — then grow your plugin as your needs expand. Once you understand actions, filters, and safe input/output handling, you can build almost anything WordPress can do. Set up a local environment, follow the steps above, and ship your first plugin today.