WordPress Development
How to Build a WordPress Plugin: A Beginner Developer Guide
Every powerful WordPress site runs on plugins. Here is how to build your own — from the minimal plugin file to settings pages, security practices, and submitting to the repository.
Every WordPress plugin starts the same way: a PHP file with a specific comment block that tells WordPress the plugin exists. From that minimal foundation, you can build anything from a simple shortcode to a complete SaaS application. This guide covers the fundamentals of building your first WordPress plugin correctly.
Why build a custom plugin
- Functionality that no existing plugin provides: niche business requirements, proprietary integrations, or custom workflows that no off-the-shelf plugin addresses
- Replacing multiple plugins with one: sometimes a lightweight custom plugin that does exactly what you need is better than three heavyweight plugins doing 90% of what you need
- Avoiding theme dependency: custom post types, custom shortcodes, and custom functions belong in a plugin — not a theme — so they persist through theme changes
- Learning and capability building: understanding plugin development transforms your ability to diagnose issues, extend WordPress, and build client solutions
Plugin file structure
A minimal WordPress plugin consists of a single PHP file in a folder within wp-content/plugins/. The file must contain a specific header comment block for WordPress to recognise it as a plugin:
wp-content/plugins/my-plugin/my-plugin.php with the header: Plugin Name, Description, Version, Author, License, Text Domain.
More complex plugins use a directory structure: the main plugin file in the plugin root, a /includes/ folder for core PHP classes, a /admin/ folder for admin-specific functionality, a /public/ folder for frontend functionality, and /assets/ for CSS, JavaScript, and images.
Adding a shortcode
Shortcodes are the simplest way to output custom content anywhere in WordPress. Register a shortcode with add_shortcode() in your plugin:
Your callback function receives an $atts array of shortcode attributes and optional $content for enclosing shortcodes. Always use shortcode_atts() to merge with defaults and sanitise inputs. Return the output as a string — never echo it.
Adding an admin settings page
Most plugins need a settings page where users configure options. WordPress provides the Settings API for this:
Use add_options_page() or add_menu_page() in a function hooked to admin_menu. This adds your plugin settings page to the WordPress admin menu.
Use register_setting() to register your option name and a sanitisation callback. Use add_settings_section() and add_settings_field() to define the form structure.
Create the settings page callback function. Use settings_fields() and do_settings_sections() to output the registered settings form. WordPress handles nonce verification and sanitisation.
Use get_option() to retrieve saved settings throughout your plugin. Store all plugin settings under a single option key as an array to minimise database reads.
Enqueueing scripts and styles
Never hardcode script or style tags in plugin output. Always use wp_enqueue_scripts for front-end assets and admin_enqueue_scripts for admin-only assets. Benefits: correct loading order, dependency management, version cache-busting, and conflict prevention with other plugins.
Plugin security fundamentals
- Sanitise all input: never trust user-supplied data. Use sanitize_text_field(), sanitize_email(), intval(), absint(), and wp_kses() appropriate to the data type.
- Escape all output: escape everything you output to the browser. Use esc_html(), esc_attr(), esc_url(), wp_kses_post() depending on context.
- Verify nonces: any form submission or AJAX request from your plugin must include a nonce verified with wp_verify_nonce() or check_admin_referer(). This prevents CSRF attacks.
- Check capabilities: always verify the current user has the required capability before performing privileged operations. Use current_user_can() before any admin action.
- Prepare database queries: never build SQL strings by concatenating user input. Always use $wpdb->prepare() to parameterise queries.
Plugin boilerplates
Starting from a well-structured boilerplate saves significant setup time and establishes best practices from the beginning:
WordPress has specific PHP, JavaScript, HTML, and CSS coding standards documented at developer.wordpress.org. Following them makes your plugin more maintainable, more compatible with other code, and more likely to pass plugin review if you submit to the WordPress Plugin Directory.
Need a custom WordPress plugin built?
Simple Automation Solutions builds custom WordPress plugins for businesses worldwide — from simple shortcodes to complex multi-page admin tools.
Frequently asked questions
How do I submit a plugin to the WordPress Plugin Directory?+
Go to wordpress.org/plugins/developers/ and click ‘Add Your Plugin’. Submit your plugin as a ZIP file along with a description. The WordPress Plugin Review Team manually reviews submissions for security and guideline compliance. Review typically takes 1-4 weeks. Your plugin must follow the WordPress Plugin Handbook guidelines — no obfuscated code, proper sanitisation and escaping, no calling external files without disclosure, and GPL-compatible licensing.
Should I use Object-Oriented Programming or procedural PHP for WordPress plugins?+
Both work. Simple single-purpose plugins are often cleaner with procedural PHP — straightforward functions hooked into WordPress. Plugins with multiple interconnected components (admin settings, public output, AJAX handlers, API integrations) benefit from OOP — classes provide namespacing, encapsulation, and better testability. The WPPB boilerplate uses OOP architecture. For your first plugin, start procedurally; move to OOP as complexity increases.
How do I make my WordPress plugin translatable?+
Use WordPress internationalisation functions throughout your plugin: __() for strings that need translation, _e() for strings that are echoed, and sprintf() patterns for strings with variable content. Set a unique text domain in your plugin header and use load_plugin_textdomain() to load translation files. Place .pot, .po, and .mo translation files in a /languages/ subdirectory. This allows translators to create language files for your plugin without modifying any code.
