Building your first WordPress plugin can seem daunting. The hooks system, the database APIs, the admin interface — there’s a lot to learn. But the fundamentals are surprisingly simple. A WordPress plugin is just a PHP file with a specific header that WordPress recognizes. Everything else is built on that foundation.
This tutorial walks through building a complete WordPress plugin from scratch, covering every step from the plugin header to WordPress.org submission.
The Plugin Header
Every WordPress plugin starts with a plugin header. Create a directory in wp-content/plugins with your plugin name. Create a PHP file with the same name. The top of the file must include a plugin header comment with the plugin name, description, version, author, and license. This header tells WordPress that this is a plugin and displays it in the Plugins admin page.
The minimum required fields are Plugin Name and Version. Add a URI field linking to your plugin’s homepage and an Author URI linking to your website. For plugins submitted to WordPress.org, the license must be GPLv2 or later.
Registering Hooks
After the plugin header, define an activation hook and a deactivation hook. register_activation_hook() runs code when the plugin is activated. register_deactivation_hook() runs code when it’s deactivated. Use these hooks to set up default options, create database tables, or flush rewrite rules.
For the plugin’s main functionality, hook into WordPress actions and filters using add_action() and add_filter(). The most common hook is init, which runs after WordPress is loaded and is used for registering custom post types, taxonomies, and shortcodes.
Adding an Admin Page
Most plugins need an admin settings page. Use the admin_menu action to register your admin page. add_menu_page() adds a top-level menu item. add_submenu_page() adds a submenu under an existing menu. In your page callback function, output the HTML for your settings page.
Use the Settings API for standard plugin settings pages. register_setting() tells WordPress about your setting. add_settings_section() and add_settings_field() create the form fields. do_settings_sections() renders them in your admin page. This API handles form submission, validation, and error messages automatically.
Creating a Shortcode
Shortcodes allow users to embed your plugin’s functionality in posts and pages. Use add_shortcode() to register a shortcode. The callback function receives the shortcode attributes and content, and returns the HTML output. Keep shortcode callbacks simple — complex logic should be in helper functions or classes.
Return the output from the shortcode callback rather than echoing it. Shortcodes should return a string that replaces the shortcode tag in the post content.
Adding Custom Post Types
Custom post types extend WordPress beyond posts and pages. Use register_post_type() during the init hook to register your custom content type. Define labels, supported features, and the URL structure. Register a taxonomy with register_taxonomy() if you need to categorize your custom post type items.
Flush rewrite rules during activation so your custom post type URLs work. Add custom meta boxes with add_meta_box() for additional data fields on your custom post type editing screen.
Preparing for WordPress.org
When your plugin is ready, prepare it for the WordPress.org plugin directory. Create a README.txt file using the WordPress plugin readme format. Check your code with PHPCS against WordPress coding standards. Ensure all text strings are internationalized with __() and _e(). Add a license and update URI to the plugin header.
Submit your plugin through the WordPress.org plugin submission form. The review team will check your code for security issues, coding standards compliance, and proper documentation.
The Bottom Line
Building a WordPress plugin from scratch follows a consistent pattern. Start with the plugin header, add hooks for activation and deactivation, create an admin settings page, register shortcodes and custom post types, and prepare your plugin for submission. Each plugin you build will follow this same structure, with variations only in the specific functionality you implement.