Anyone can write a WordPress plugin that works on their own machine. Writing one that survives contact with real users, other plugins, and future WordPress core updates is a different skill. This guide covers the practices that separate a plugin you can maintain for years from one you'll be afraid to touch after six months.
Start With a Proper Structure
Resist the urge to cram everything into one file. A typical well-organized plugin looks like this:
my-plugin/
├── my-plugin.php # Main plugin file, bootstraps everything
├── includes/
│ ├── class-activator.php
│ ├── class-deactivator.php
│ └── class-plugin.php
├── admin/
├── public/
├── languages/
└── uninstall.php
The main file should do as little as possible: define constants, check requirements, and hand off to a loader class. Business logic doesn't belong in the file WordPress boots.
Namespace Everything
Every global function, class, and constant you define lives in the same namespace as every other plugin and theme on the site. functions.php tutorials aside, add() and Settings are terrible names in a shared global scope.
Use PHP namespaces or, at minimum, a unique prefix:
namespace AcmeCorp\MyPlugin;
class Settings_Page { /* ... */ }
Do the same for hooks, options, and transients: acme_myplugin_settings, not settings. This single habit prevents more production incidents than almost anything else on this list.
Use Hooks, Don't Fight Them
WordPress's action and filter system is the plugin API. If you find yourself patching core files or directly querying tables that a hook already exposes, stop — there's almost always a do_action or apply_filters call already in place.
add_action( 'save_post', __NAMESPACE__ . '\\sync_external_record', 10, 3 );
add_filter( 'the_content', __NAMESPACE__ . '\\append_disclaimer' );
Prefer specific hooks over generic ones (save_post_{post_type} over save_post) to avoid unnecessary work firing on every post type.
Sanitize on the Way In, Escape on the Way Out
This is the single most important security rule in WordPress development:
- Sanitize input the moment it enters your code —
sanitize_text_field(),absint(),sanitize_email(). - Validate it against expected values — is it one of the allowed options, within range, the right format?
- Escape output the moment it leaves your code and heads to the browser —
esc_html(),esc_attr(),esc_url().
$name = sanitize_text_field( wp_unslash( $_POST['name'] ?? '' ) );
echo '<p>Hello, ' . esc_html( $name ) . '</p>';
Never trust $_GET, $_POST, $_REQUEST, or even data coming from your own database if it originated from user input long ago. Escape at the point of output, not the point of storage — storing pre-escaped HTML makes it unusable anywhere else.
Use the $wpdb Prepare Pattern for Custom Queries
Reach for WP_Query, get_posts(), or the Options/Meta APIs before writing raw SQL. When you genuinely need a custom query, always use $wpdb->prepare():
global $wpdb;
$results = $wpdb->get_results(
$wpdb->prepare(
"SELECT * FROM {$wpdb->prefix}acme_orders WHERE status = %s AND total > %d",
$status,
$minimum
)
);
Never concatenate variables directly into SQL strings, even ones you think are "safe."
Enqueue Assets Correctly
Don't hardcode <script> and <link> tags in template output. Use wp_enqueue_script() and wp_enqueue_style() with proper dependencies and versioning, and only load assets where they're needed:
function acme_enqueue_admin_assets( $hook ) {
if ( 'toplevel_page_acme-settings' !== $hook ) {
return;
}
wp_enqueue_style(
'acme-admin',
plugins_url( 'admin/css/admin.css', __FILE__ ),
[],
ACME_PLUGIN_VERSION
);
}
add_action( 'admin_enqueue_scripts', 'acme_enqueue_admin_assets' );
Loading every asset on every admin page is one of the most common causes of plugin conflicts and admin dashboard bloat.
Handle Activation, Deactivation, and Uninstall Deliberately
- Activation: create tables, set default options, schedule cron events. Keep it idempotent — activation can run more than once.
- Deactivation: clear scheduled events, flush rewrite rules if you registered custom post types. Don't delete user data.
- Uninstall (
uninstall.php): this is the only place you should remove options, tables, and stored data — and only if the user explicitly confirms data removal matters to your plugin's settings.
register_activation_hook( __FILE__, __NAMESPACE__ . '\\activate' );
register_deactivation_hook( __FILE__, __NAMESPACE__ . '\\deactivate' );
Write for Compatibility, Not Just Your Own Site
- Check
function_exists()or class existence before relying on other plugins. - Use
WP_DEBUGandWP_DEBUG_LOGduring development, and fix every notice and warning that shows up — they're often symptoms of real bugs. - Test against the minimum PHP and WordPress versions declared in your plugin header, not just whatever you happen to be running locally.
- Avoid modifying global state (like
$post) without restoring it (wp_reset_postdata()after custom loops).
Internationalize From Day One
Wrap every user-facing string, even if you only ship in English today:
esc_html_e( 'Settings saved.', 'my-plugin' );
Retrofitting translation functions into thousands of strings later is tedious and error-prone. Doing it from the first commit costs almost nothing.
Version Your Data Migrations
When your plugin's stored data format changes between versions, write an explicit upgrade routine keyed off a stored version number, run on plugins_loaded or activation:
$installed_version = get_option( 'acme_myplugin_version', '0' );
if ( version_compare( $installed_version, '2.0.0', '<' ) ) {
acme_migrate_to_v2();
update_option( 'acme_myplugin_version', '2.0.0' );
}
Sites update plugins at wildly different times — you need a path from every prior version to the current one, not just the last release.
Final Thought
None of this is exotic. It's the accumulated, hard-won conventions of a platform that runs on a huge fraction of the web and has to tolerate thousands of plugins coexisting on the same site. Follow them from the start, and your plugin will still be maintainable — by you or by whoever inherits it — years from now.
