Buzzetty IT
wordpressJan 20, 2026

The Architect’s Guide: How to Build Your First WordPress Plugin

Building a WordPress plugin is the single best way to extend the functionality of a website without hacking the core files. Whether you want to add a simple contact form or a complex e-commerce engine, it all starts with the same foundation.

The Architect’s Guide: How to Build Your First WordPress Plugin

Building a WordPress plugin is the single best way to extend the functionality of a website without hacking the core files. Whether you want to add a simple contact form or a complex e-commerce engine, it all starts with the same foundation.

This guide will walk you through creating a "Site Maintenance Mode" plugin. It is a practical, real-world example that demonstrates the core concepts of WordPress development: hooks, permissions, and front-end rendering.

Prerequisites

Before we begin, ensure you have:

  1. A Local WordPress Environment: Tools like LocalWP, XAMPP, or Docker.
  2. Code Editor: VS Code, Sublime Text, or PHPStorm.
  3. Access to the File System: Specifically the /wp-content/plugins/ directory.

Step 1: The Foundation (Folder Structure)

WordPress looks for plugins in the wp-content/plugins directory. To keep things organized, every plugin should have its own folder.

  1. Navigate to your WordPress installation: .../wp-content/plugins/
  2. Create a new folder named simple-maintenance-mode.
  3. Inside that folder, create a PHP file with the same name: simple-maintenance-mode.php.

Why the same name? It is a WordPress standard that helps keep your directory structure predictable.

Step 2: The Plugin Header

WordPress "reads" your plugin through a specific comment block at the top of your main PHP file. Without this, WordPress will not recognize your code as a plugin.

Open simple-maintenance-mode.php and paste the following code:

PHP


<?php
/**
* Plugin Name: Simple Maintenance Mode
* Plugin URI: https://example.com/simple-maintenance-mode
* Description: A lightweight plugin to enable maintenance mode for visitors while allowing admins to access the site.
* Version: 1.0.0
* Author: Tech Writer
* Author URI: https://example.com
* License: GPL2
*/

// Security Check: Prevent direct access to this file
if ( ! defined( 'ABSPATH' ) ) {
exit; // Exit if accessed directly
}

Key Takeaway: The defined( 'ABSPATH' ) check is a critical security measure. It ensures no one can run your PHP file directly from the browser to exploit vulnerabilities.

Step 3: Understanding "Hooks"

The magic of WordPress lies in Hooks. They allow you to "hook" your code into specific points of the WordPress execution timeline without modifying core files.

  1. Actions (add_action): "Do this when X happens." (e.g., when the page loads, save data).
  2. Filters (add_filter): "Change this data before showing it." (e.g., modify the content of a post).

For our maintenance plugin, we will use an Action to interrupt the page load process. The diagram below illustrates how our plugin's code "hooks" into the WordPress execution timeline.



Step 4: Writing the Logic

We need to intercept the user request before the page loads. If the user is not logged in as an administrator, we will stop the page load and show a message.

Add this code below your security check:

PHP


function smm_activate_maintenance_mode() {
// 1. Check if the user is capable of managing options (Administrator)
// If they are an admin, return immediately and let them see the site normally.
if ( current_user_can( 'manage_options' ) ) {
return;
}

// 2. If the user is NOT an admin, stop WordPress execution and show a message.
$title = 'Site Under Maintenance';
$message = '<h1>We are currently upgrading our site.</h1><p>Please check back in an hour.</p>';

// wp_die() kills the execution and displays an HTML page with our message.
wp_die( $message, $title, array( 'response' => 503 ) );
}

// Hook our function to 'get_header'
// This event runs before the main template is displayed.
add_action( 'get_header', 'smm_activate_maintenance_mode' );

Step 5: Adding an Activation Message (Optional)

It is good practice to let the user know something happened when they activate the plugin. We can use register_activation_hook to run code specifically when the "Activate" button is clicked in the dashboard.

Add this to the bottom of your file:

PHP


register_activation_hook( __FILE__, 'smm_plugin_activation' );

function smm_plugin_activation() {
// Usually used to create database tables or set default options.
// For now, we will just log a simple entry to the error log for debugging.
error_log( 'Simple Maintenance Mode plugin activated!' );
}

Step 6: Testing Your Plugin

  1. Log in to your WordPress Dashboard.
  2. Go to Plugins > Installed Plugins.
  3. Locate "Simple Maintenance Mode" and click Activate.
  4. Test as Admin: Visit your homepage. You should see the site normally.
  5. Test as Visitor: Open an Incognito/Private window (where you are not logged in) and visit your homepage. You should see the "Site Under Maintenance" message.

Best Practices for Future Development

As you move to complex plugins, adhere to these three golden rules:

  1. Prefix Everything: Always prefix your functions, classes, and variables (e.g., smm_ for Simple Maintenance Mode) to avoid conflicts with other plugins.
  2. Sanitize and Escape: Never trust user input. Always sanitize data before saving it (sanitize_text_field) and escape data before outputting it (esc_html).
  3. Separate Logic: As your plugin grows, don't keep everything in one file. Separate CSS, JavaScript, and PHP classes into their own subfolders.