How to Build a Custom WordPress Plugin from Scratch: A Developer’s Walkthrough

Building a custom WordPress plugin is one of the most valuable skills a WordPress developer can have. Plugins let you add features to WordPress without modifying core files, making your code portable, maintainable, and update-safe. Whether you need a simple shortcode or a complex application with its own database tables, the plugin architecture handles it all.

This guide walks you through the complete process of building a WordPress plugin from an empty file to a production-ready feature.

The Plugin File Structure

A WordPress plugin starts with a single PHP file inside the wp-content/plugins/ directory. For anything beyond the simplest functionality, create a dedicated folder for your plugin. A well-organized plugin structure typically includes the main plugin file at the root, an includes/ directory for PHP class files and helper functions, an admin/ directory for admin-facing code, a public/ directory for frontend code, an assets/ directory for CSS, JavaScript, and images, and a languages/ directory for translation files.

This structure keeps your code organized and makes it easy for other developers to navigate your plugin.

The Plugin Header

WordPress identifies a plugin by a special comment block at the top of your main plugin file. This header tells WordPress the plugin’s name, description, version, author, license, and minimum requirements. Without this header, WordPress will not recognize the file as a plugin.

The required fields are Plugin Name and at a minimum, Description and Version. The “Requires at least” and “Requires PHP” fields help WordPress warn users if their environment does not meet your plugin’s requirements.

Hooks: Actions and Filters

Hooks are the foundation of WordPress plugin development. They let your code run at specific points during WordPress’s execution without modifying core files. There are two types: actions and filters.

Actions are triggered at specific events — when WordPress initializes, when a post is saved, when a page loads, when a user logs in. You “hook” your function to an action, and WordPress calls your function when that event occurs. For example, hooking a function to the wp_enqueue_scripts action lets you add CSS and JavaScript files to the frontend at the correct time.

Filters let you modify data as it passes through WordPress’s processing pipeline. When WordPress prepares a post title for display, it runs the title through a series of filters. You can hook into that filter to modify the title — adding a prefix, stripping certain characters, or transforming it entirely. The key difference from actions is that filters receive data, modify it, and must return the modified data.

Understanding hooks is understanding WordPress development. Every feature you build in a plugin connects to WordPress through one or more hooks.

Creating a Shortcode

Shortcodes let users insert dynamic content into posts and pages by typing a simple tag like [my_feature]. They are one of the easiest and most user-friendly ways to expose plugin functionality.

You register a shortcode using the add_shortcode() function, passing the tag name and a callback function. The callback receives any attributes the user passes (like [my_feature color="blue" count="5"]) and returns the HTML output that replaces the shortcode in the rendered page.

Important: shortcode callbacks must return their output, not echo it. Using echo will produce output in the wrong location on the page.

Adding an Admin Settings Page

Most plugins need a settings page where site administrators can configure the plugin’s behavior. WordPress provides a complete settings API for this purpose.

The process involves three steps: register your settings using register_setting(), which tells WordPress what options your plugin uses and how to validate them. Add settings sections and fields using add_settings_section() and add_settings_field(), which define the UI elements on your settings page. Create the page itself using add_menu_page() or add_submenu_page() and render it with a callback that outputs a form containing your registered settings fields.

Using the Settings API rather than handling form submissions manually gives you automatic nonce verification, data sanitization, and integration with WordPress’s options storage system.

Working with the Database

For simple key-value data, WordPress’s Options API (get_option(), update_option()) is sufficient. For structured data that does not fit neatly into WordPress’s existing post or taxonomy system, you may need custom database tables.

Create custom tables during plugin activation using the register_activation_hook() function. Write your table creation SQL using WordPress’s dbDelta() function, which intelligently creates new tables or modifies existing ones to match your schema. Always prefix your table names with $wpdb->prefix to support WordPress multisite installations.

Use the $wpdb global object for all database operations. The $wpdb->prepare() method provides parameterized queries that prevent SQL injection — never concatenate user input directly into SQL strings.

Enqueueing Scripts and Styles

Never add CSS or JavaScript by echoing script and link tags directly into your output. WordPress has a proper enqueueing system that manages dependencies, prevents duplicate loading, and allows other plugins and themes to interact with your assets.

Use wp_enqueue_style() for CSS and wp_enqueue_script() for JavaScript, hooked to wp_enqueue_scripts for frontend assets or admin_enqueue_scripts for admin assets. Each enqueued asset gets a unique handle, a file path, an array of dependencies, a version number, and additional options like loading in the footer or specifying media queries.

For passing PHP data to JavaScript (like AJAX URLs, nonces, or configuration values), use wp_localize_script() or the newer wp_add_inline_script(). This keeps your JavaScript files static and cacheable while still providing server-side data.

AJAX in Plugins

Many plugins need to communicate with the server without reloading the page. WordPress provides a standardized AJAX handler through the admin-ajax.php endpoint.

Register your AJAX handlers by hooking functions to wp_ajax_{action} (for logged-in users) and wp_ajax_nopriv_{action} (for visitors). On the JavaScript side, send requests to the ajaxurl variable (available in admin) or the URL you localized, including a nonce for security verification.

For modern plugins, the REST API is increasingly preferred over admin-ajax.php for AJAX functionality. It provides better URL structure, standard HTTP methods, built-in JSON handling, and better performance under load.

Activation, Deactivation, and Uninstallation

WordPress provides three hooks for plugin lifecycle events. The activation hook runs when a user activates your plugin — use it to create database tables, set default options, and flush rewrite rules. The deactivation hook runs when the plugin is deactivated — use it to clean up temporary data and scheduled tasks, but leave settings and database tables intact in case the user reactivates.

The uninstall hook or uninstall.php file runs when the plugin is deleted through the admin. This is where you remove all traces of your plugin: delete options, drop custom tables, remove scheduled cron events, and clean up any files your plugin created.

Security Best Practices

Security must be built into every layer of your plugin. Validate and sanitize all input using WordPress’s sanitization functions — sanitize_text_field(), sanitize_email(), absint(), and others. Escape all output using esc_html(), esc_attr(), esc_url(), and wp_kses(). Use nonces to verify form submissions and AJAX requests come from your site. Check user capabilities before performing any action with current_user_can().

Never trust user input, even from admin users. Always prepare database queries with $wpdb->prepare(). And never use eval(), extract(), or similar functions that execute arbitrary code.

A well-built WordPress plugin follows WordPress coding standards, uses hooks instead of modifying files, respects the database through proper APIs, handles security at every boundary, and cleans up after itself when removed. Master these fundamentals, and you can build anything the platform supports.