WordPress plugin development starts with creating a PHP file with the correct header comment, hooking into WordPress actions and filters to extend functionality, and following the WordPress coding standards for security, data handling, and user interface. This guide walks you through the fundamentals so you can build, test, and distribute your first WordPress plugin.
What Is a WordPress Plugin and How Does It Work?
A WordPress plugin is a PHP program that extends or modifies WordPress functionality without changing core files. When WordPress loads, it scans the wp-content/plugins/ directory for activated plugins and includes their main files, executing any code hooked into WordPress’s action and filter system.
This architecture means plugins can add new features, modify existing behaviour, integrate external services, create custom post types, add admin pages, and much more — all without editing a single core file.
How Do You Create Your First Plugin File?
Every plugin starts with a main PHP file containing a header comment that WordPress reads to identify the plugin:
- Create a new folder in
wp-content/plugins/with your plugin name (e.g.,my-first-plugin). - Create a PHP file inside it (e.g.,
my-first-plugin.php). - Add the plugin header comment at the top: Plugin Name, Description, Version, Author, and Licence (typically GPL v2).
- Add an
if (!defined('ABSPATH')) exit;security check to prevent direct file access.
With just the header comment, your plugin appears in the WordPress admin under Plugins and can be activated. All functionality is added by hooking into WordPress’s event system.
What Are Hooks, Actions, and Filters?
Hooks are the backbone of WordPress plugin development. They let your plugin execute code at specific points in WordPress’s lifecycle:
| Concept | Purpose | Example |
|---|---|---|
| Action hook | Execute code when something happens | add_action('wp_footer', 'my_footer_code') |
| Filter hook | Modify data before WordPress uses it | add_filter('the_content', 'my_content_modifier') |
| Priority | Controls execution order (lower = earlier) | Default is 10; use 5 to run before defaults, 20 to run after |
| Accepted args | Number of arguments your function receives | Filters pass the value being filtered; some hooks pass multiple arguments |
Key actions to know: init (runs after WordPress loads, before output), admin_menu (add admin pages), wp_enqueue_scripts (load CSS/JS), save_post (runs when a post is saved), rest_api_init (register REST API routes).
Key filters to know: the_content (modify post content), the_title (modify post title), wp_mail (modify outgoing emails), query_vars (add custom query parameters).
How Do You Add a Settings Page?
Most plugins need a settings page where site administrators can configure options. WordPress provides a Settings API for this:
- Use
add_action('admin_menu', ...)to register a menu page withadd_options_page()oradd_menu_page(). - Register settings with
register_setting()and define sections and fields withadd_settings_section()andadd_settings_field(). - In your settings page callback, wrap the form in
settings_fields()anddo_settings_sections()to render fields and handle CSRF protection automatically. - Access saved settings with
get_option('your_option_name')anywhere in your plugin.
Always sanitise and validate user input. Use sanitize_text_field(), absint(), and wp_kses() to clean data before saving.
What Security Practices Must You Follow?
Security is non-negotiable in plugin development. A vulnerable plugin can compromise every site that installs it.
- Nonces: Use
wp_nonce_field()andwp_verify_nonce()on every form submission and AJAX request to prevent CSRF attacks. - Capability checks: Always verify user permissions with
current_user_can()before executing privileged actions. - Data sanitisation: Sanitise all input on save, escape all output on display. Use
esc_html(),esc_attr(),esc_url(), andwp_kses_post(). - Prepared statements: When writing custom database queries, always use
$wpdb->prepare()to prevent SQL injection. - File operations: Never trust user-uploaded file names or types. Use WordPress’s built-in media handling where possible.
How Do You Test and Debug Your Plugin?
- Enable
WP_DEBUGandWP_DEBUG_LOGinwp-config.phpduring development. - Install the Query Monitor plugin to inspect database queries, hooks, and performance.
- Test with multiple themes, especially the latest default theme, to ensure compatibility.
- Test with PHP 8.x as WordPress moves towards requiring modern PHP versions.
- Use PHPUnit with the WordPress test suite for automated testing.
Do I need to know PHP to build WordPress plugins?
Yes. PHP is the primary language for WordPress development. You should be comfortable with PHP basics — variables, functions, arrays, classes, and file inclusion. Understanding object-oriented PHP helps with larger plugins. HTML, CSS, and JavaScript knowledge is needed for admin interfaces and front-end features.
Can I sell WordPress plugins I build?
Yes. WordPress plugins can be distributed free on WordPress.org or sold through marketplaces like CodeCanyon, or directly from your own website. If selling, you need a licence key system and update server. Plugins built on GPL-licenced WordPress code must also be GPL-licenced, but you can still charge for access, support, and updates.
How do I handle plugin updates for users?
Plugins hosted on WordPress.org get automatic update distribution through WordPress’s built-in update system. For self-hosted premium plugins, you need a licence server that checks for updates — solutions like the Software Licensing add-on for Easy Digital Downloads or custom update checkers handle this. The MAD’s own products use this approach for distributing updates securely.
