Skip to content

How to Create WordPress Plugin from Scratch

This guide walks you through how to create a WordPress plugin from scratch, covering everything from setup to activation. You’ll learn best practices, essential code structure, and how to make your plugin functional and secure.

Key Takeaways

  • Understand plugin basics: Learn what a WordPress plugin is and how it extends site functionality.
  • Set up your development environment: Use a local server like XAMPP or Local by Flywheel for safe testing.
  • Create the main plugin file: Name it properly and add required headers for WordPress to recognize it.
  • Add functionality with hooks: Use actions and filters to integrate your code into WordPress.
  • Test and debug your plugin: Check for errors and ensure compatibility with your theme and other plugins.
  • Deploy and maintain: Upload your plugin and keep it updated for security and performance.

Introduction: Why Create a WordPress Plugin?

WordPress powers over 40% of all websites, and plugins are the backbone of its flexibility. Whether you want to add a contact form, improve SEO, or create custom features, knowing how to create a WordPress plugin from scratch gives you full control.

Unlike using pre-built plugins, building your own ensures lightweight code, better security, and tailored functionality. In this guide, you’ll learn the complete process—from planning to publishing—so you can create plugins that solve real problems.

Step 1: Plan Your Plugin

Before writing code, define what your plugin will do. Ask yourself:

  • What problem does it solve?
  • Who is the target user?
  • Will it need settings or a dashboard?

For this tutorial, we’ll build a simple “Hello World” plugin that displays a message in the admin dashboard. This helps you understand the core structure.

Choose a Unique Name

Your plugin name should be unique to avoid conflicts. Use lowercase letters and hyphens (e.g., hello-world-admin).

Check for Existing Plugins

Search the WordPress Plugin Directory to ensure your idea isn’t already taken. This also helps you avoid reinventing the wheel.

Step 2: Set Up Your Development Environment

You need a local WordPress installation to test your plugin safely.

Install a Local Server

Use tools like:

  • XAMPP (Windows, macOS, Linux)
  • Local by Flywheel (Beginner-friendly)
  • MAMP (macOS and Windows)

Once installed, create a new WordPress site. This keeps your live site safe while you develop.

Access Your Plugin Folder

Navigate to:
wp-content/plugins/

Create a new folder for your plugin:
wp-content/plugins/hello-world-admin/

Step 3: Create the Main Plugin File

How to Create WordPress Plugin from Scratch

Visual guide about How to Create WordPress Plugin from Scratch

Image source: media.geeksforgeeks.org

Every plugin needs a main PHP file with a header comment.

Create the PHP File

Inside your plugin folder, create:
hello-world-admin.php

Add this code:

<?php  
/*  
Plugin Name: Hello World Admin  
Description: Displays a "Hello World" message in the WordPress admin dashboard.  
Version: 1.0  
Author: Your Name  
*/  
?>

Activate Your Plugin

1. Go to your WordPress admin dashboard.
2. Click Plugins > Installed Plugins.
3. Find “Hello World Admin” and click Activate.

Even though it doesn’t do anything yet, WordPress now recognizes your plugin.

Step 4: Add Basic Functionality

Now, let’s make your plugin display a message.

Use WordPress Hooks

WordPress uses hooks to let plugins interact with core functions. We’ll use the admin_notices hook to show a message in the dashboard.

Add this code below the header:

function hello_world_admin_notice() {  
    echo '<div class="notice notice-success is-dismissible">  
        <p><strong>Hello World!</strong> Your plugin is working.</p>  
    </div>';  
}  
add_action('admin_notices', 'hello_world_admin_notice');

Test Your Plugin

Refresh your admin dashboard. You should see a green notice with your message. If not, check for syntax errors in your code.

Step 5: Enhance Your Plugin

Let’s add a settings page so users can customize the message.

Create a Settings Page

Add this code to register a menu item:

function hello_world_admin_menu() {  
    add_menu_page(  
        'Hello World Settings',  
        'Hello World',  
        'manage_options',  
        'hello-world-settings',  
        'hello_world_settings_page',  
        'dashicons-smiley',  
        6  
    );  
}  
add_action('admin_menu', 'hello_world_admin_menu');

Build the Settings Form

Add this function to display the form:

function hello_world_settings_page() {  
    ?>  
    <div class="wrap">  
        <h1>Hello World Settings</h1>  
        <form method="post" action="options.php">  
            <?php  
            settings_fields('hello_world_settings_group');  
            do_settings_sections('hello-world-settings');  
            submit_button();  
            ?>  
        </form>  
    </div>  
    <?php  
}

Register Settings

Add this to save user input:

function hello_world_register_settings() {  
    register_setting('hello_world_settings_group', 'hello_world_message');  
    add_settings_section('hello_world_main_section', 'Main Settings', null, 'hello-world-settings');  
    add_settings_field('hello_world_message_field', 'Custom Message', 'hello_world_message_field_callback', 'hello-world-settings', 'hello_world_main_section');  
}  
add_action('admin_init', 'hello_world_register_settings');

Create the Input Field

Add this callback function:

function hello_world_message_field_callback() {  
    $message = get_option('hello_world_message', 'Hello World!');  
    echo '<input type="text" name="hello_world_message" value="' . esc_attr($message) . '" class="regular-text">';  
}

Update the Notice

Modify the notice function to use the saved message:

function hello_world_admin_notice() {  
    $message = get_option('hello_world_message', 'Hello World!');  
    echo '<div class="notice notice-success is-dismissible">  
        <p><strong>' . esc_html($message) . '</strong></p>  
    </div>';  
}

Now, users can change the message from the settings page.

Step 6: Test and Debug

Always test your plugin thoroughly.

Check for Errors

Enable debugging in wp-config.php:

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

This logs errors to wp-content/debug.log.

Test Compatibility

Switch themes and test with other plugins. If conflicts occur, check for:

  • Duplicate function names
  • Improperly enqueued scripts
  • Missing capability checks

Step 7: Deploy Your Plugin

Once tested, upload your plugin to a live site.

Zip Your Plugin Folder

Compress the entire folder (e.g., hello-world-admin.zip).

Install on Live Site

1. Go to Plugins > Add New > Upload Plugin.
2. Choose your ZIP file and click Install Now.
3. Activate the plugin.

Maintain Your Plugin

Keep it updated for:

  • WordPress core changes
  • Security patches
  • New features

Consider publishing it on the WordPress Plugin Directory if it’s useful to others.

Troubleshooting Common Issues

Plugin Not Appearing in Dashboard?

  • Check folder and file names.
  • Ensure the plugin header is correct.
  • Verify file permissions.

White Screen of Death?

  • Disable the plugin via FTP by renaming the folder.
  • Check debug.log for errors.
  • Look for syntax errors in your code.

Settings Not Saving?

  • Verify settings_fields() and register_setting() match.
  • Ensure the form uses options.php.

Conclusion

You’ve now learned how to create a WordPress plugin from scratch—from planning to deployment. Start small, test often, and build on your skills.

Plugins are powerful tools that can transform any WordPress site. Whether you’re adding simple features or complex systems, this foundation will help you succeed.

For more advanced topics, explore creating custom post types, shortcodes, or integrating with APIs. And if you’re working with themes, check out our guide on how to create a WordPress theme with Elementor to expand your development toolkit.