Build a Custom WordPress Plugin – Easy Tutorial

By: Waqar Ahmed on Aug 15, 2025

A custom WordPress Plugin allow you to extend the functionality of your website without modifying core files. If you’re a beginner and want to create your first WordPress plugin, this guide will walk you through the process step by step in a simple and easy-to-understand way.

By the end of this tutorial, you’ll have built a basic WordPress plugin from scratch. Let’s get started!

Prerequisites

Before we begin, make sure you have:

  • A local or live WordPress installation.
  • A code editor (VS Code, Sublime Text, or Notepad++).
  • Basic understanding of PHP (but don’t worry—we’ll keep it simple!).

Step 1: Understanding custom WordPress Plugin Structure

A WordPress plugin is essentially a PHP file (or a collection of files) that adds new features to WordPress. Plugins are stored in the /wp-content/plugins/ directory.

Basic Plugin Requirements:

  1. Plugin Header Comment – Tells WordPress about your plugin (name, description, version, etc.).
  2. PHP Functions – The actual code that makes your plugin work.
  3. Hooks (Actions & Filters) – Allow your plugin to interact with WordPress core.

Step 2: Creating Your First custom WordPress Plugin

Let’s create a simple plugin that adds a custom message below each blog post.

1. Set Up the WordPress Plugin Folder & File

  • Navigate to /wp-content/plugins/ in your WordPress installation.
  • Create a new folder named my-first-plugin.
  • Inside this folder, create a PHP file named my-first-plugin.php.

2. Add the Plugin Header

Open my-first-plugin.php in your code editor and add the following header:

<?php
/**
 * Plugin Name: My First Plugin
 * Plugin URI: https://yourwebsite.com/my-first-plugin
 * Description: A simple WordPress plugin that adds a custom message below posts.
 * Version: 1.0
 * Author: Your Name
 * Author URI: https://yourwebsite.com
 * License: GPL2
 */

This header is required for WordPress to recognize your plugin. Save the file.

3. Activate the Plugin

  • Go to your WordPress admin dashboard (/wp-admin).
  • Navigate to Plugins > Installed Plugins.
  • Find “My First Plugin” and click Activate.

Right now, the plugin doesn’t do anything—but it’s officially installed!

Step 3: Adding Functionality to the Plugin

Now, let’s make the plugin display a custom message after each post.

1. Using a WordPress Hook

WordPress uses hooks (actions & filters) to allow plugins to modify behavior. We’ll use the the_content filter to add text after the post content.

Add this code below the plugin header:

function my_first_plugin_add_message( $content ) {
    if ( is_single() ) { // Only display on single posts
        $custom_message = '<div class="my-custom-message"><p>Thanks for reading! Follow me on social media.</p></div>';
        $content .= $custom_message;
    }
    return $content;
}
add_filter( 'the_content', 'my_first_plugin_add_message' );

Explanation:

  • my_first_plugin_add_message() is our custom function.
  • $content is the post content passed by WordPress.
  • is_single() ensures the message only appears on single posts (not pages or archives).
  • $content .= $custom_message appends our message to the post.
  • add_filter() hooks our function into WordPress.

2. Save & Test

  • Save the file.
  • Open a blog post on your site—you should see the message at the bottom!

Step 4: Adding CSS to your custom WordPress Plugin (Optional)

To style the message, we’ll enqueue a CSS file.

1. Create a CSS File

Inside your plugin folder (/my-first-plugin/), create a new folder named css and inside it, create a file named style.css.

Add this CSS:

.my-custom-message {
    background: #f0f0f0;
    padding: 15px;
    border-left: 4px solid #0073aa;
    margin: 20px 0;
}

2. Load the CSS in custom WordPress Plugin

Modify your my-first-plugin.php to include this code:

function my_first_plugin_enqueue_styles() {
    wp_enqueue_style(
        'my-first-plugin-styles',
        plugins_url( 'css/style.css', __FILE__ )
    );
}
add_action( 'wp_enqueue_scripts', 'my_first_plugin_enqueue_styles' );

Explanation:

  • wp_enqueue_style() loads the CSS file.
  • plugins_url() generates the correct path to the CSS file.
  • add_action() ensures the CSS loads on the front end.

Save and refresh a post—your message should now have styling!

Step 5: Adding a Settings Page (Advanced)

Let’s make the plugin customizable by adding a settings page in the WordPress admin.

1. Create an Admin Menu in custom WordPress Plugin

Add this code to my-first-plugin.php:

function my_first_plugin_settings_page() {
    add_menu_page(
        'My First Plugin Settings', // Page title
        'My First Plugin', // Menu title
        'manage_options', // Capability required
        'my-first-plugin', // Menu slug
        'my_first_plugin_settings_html', // Callback function
        'dashicons-smiley' // Icon (optional)
    );
}
add_action( 'admin_menu', 'my_first_plugin_settings_page' );

2. Create the Settings HTML

Add this function:

function my_first_plugin_settings_html() {
    ?>
    <div class="wrap">
        <h1>My First Plugin Settings</h1>
        <form method="post" action="options.php">
            <?php
            settings_fields( 'my_first_plugin_settings' );
            do_settings_sections( 'my-first-plugin' );
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

3. Register Settings

Add this code:

function my_first_plugin_register_settings() {
    register_setting( 'my_first_plugin_settings', 'my_first_plugin_message' );
    
    add_settings_section(
        'my_first_plugin_section',
        'Custom Message Settings',
        'my_first_plugin_section_html',
        'my-first-plugin'
    );

    add_settings_field(
        'my_first_plugin_message_field',
        'Message Text',
        'my_first_plugin_message_field_html',
        'my-first-plugin',
        'my_first_plugin_section'
    );
}
add_action( 'admin_init', 'my_first_plugin_register_settings' );

function my_first_plugin_section_html() {
    echo '<p>Customize the message displayed after posts.</p>';
}

function my_first_plugin_message_field_html() {
    $message = get_option( 'my_first_plugin_message' );
    echo '<input type="text" name="my_first_plugin_message" value="' . esc_attr( $message ) . '" style="width: 300px;">';
}

4. Modify the custom WordPress Plugin to Use the Saved Message

Update the my_first_plugin_add_message function:

function my_first_plugin_add_message( $content ) {
    if ( is_single() ) {
        $custom_message = get_option( 'my_first_plugin_message', 'Thanks for reading! Follow me on social media.' );
        $content .= '<div class="my-custom-message"><p>' . esc_html( $custom_message ) . '</p></div>';
    }
    return $content;
}

Now, go to Settings > My First Plugin in WordPress admin and change the message. It will update on your posts!

Step 6: Testing & Debugging

  • Test your plugin on different post types.
  • Use error_log() for debugging (e.g., error_log(print_r($variable, true));).
  • Check for PHP errors in wp-config.php by enabling WP_DEBUG.

Step 7: Preparing for Distribution (Optional)

If you want to share your plugin:

  1. Add a README.txt (follow WordPress plugin guidelines).
  2. Compress the folder into a ZIP file.
  3. Upload to WordPress.org (if submitting to the Plugin Directory).

Conclusion

Congratulations! You’ve just built your first WordPress plugin from scratch. You learned:
✅ How to create a basic plugin
✅ How to use hooks (actions & filters)
✅ How to add CSS and admin settings
✅ How to make the plugin customizable

Now, you can experiment with more features like shortcodes, widgets, or custom post types. The possibilities are endless!

Next Steps:

  • Explore the WordPress Plugin Handbook.
  • Try building a plugin with a shortcode (add_shortcode()).
  • Learn about security best practices (e.g., sanitizing inputs).

Happy coding! 🚀