---
name: wordpress-plugin-conventions
description: Use when writing or modifying a WordPress plugin's PHP code. Baseline structural/security conventions to follow without being told each time.
---

# WordPress Plugin Conventions

Baseline conventions for first-party WordPress plugin code. Follow these
without needing to be told in every brief.

## File structure

```
plugin-slug/
  plugin-slug.php        — main file: header, constants, bootstrap class
  includes/
    class-<prefix>-*.php — one class per concern, class-based not procedural
  admin/                  — admin-only UI (settings pages, dashboards)
    assets/{css,js}/
  languages/              — .pot/.po/.mo if the plugin is translatable
```

## Main file skeleton

```php
<?php
/**
 * Plugin Name: ...
 * Plugin URI: ...
 * Description: ...
 * Version: 1.0.0
 * Author: ...
 * Author URI: ...
 * License: GPL v2 or later
 * License URI: https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: plugin-slug
 * Requires PHP: 7.4
 */

if (!defined('ABSPATH')) {
    exit;
}

define('PREFIX_VERSION', '1.0.0');
define('PREFIX_PATH', plugin_dir_path(__FILE__));
define('PREFIX_URL', plugin_dir_url(__FILE__));

require_once PREFIX_PATH . 'includes/class-prefix-thing.php';

class Prefix_Main {
    private static $instance = null;
    public static function instance() {
        if (null === self::$instance) { self::$instance = new self(); }
        return self::$instance;
    }
    private function __construct() { /* hook registration only */ }
    public static function activate() { /* create tables/options/dirs */ }
    public static function deactivate() { /* reverse activate() side effects */ }
}
register_activation_hook(__FILE__, ['Prefix_Main', 'activate']);
register_deactivation_hook(__FILE__, ['Prefix_Main', 'deactivate']);
add_action('plugins_loaded', ['Prefix_Main', 'instance']);
```

Every included file starts with `if (!defined('ABSPATH')) exit;` — never
`define('ABSPATH', ...) &&` or any variant, exactly the guard-and-exit
form, so the file can never be requested directly over HTTP.

## Every file must pass `php -l` before you consider a task done

Not optional, not "probably fine" — actually run it, on every changed
file, every time. This is the cheapest possible check and catches a
meaningful fraction of real mistakes (typos, mismatched braces from a
find/replace, etc.) before they ever reach a live site.

## Security baseline

- Nonces on every form/AJAX action: `wp_nonce_field()` /
  `check_admin_referer()` / `check_ajax_referer()`.
- Capability checks before any privileged action:
  `current_user_can('manage_options')` (or the narrowest capability that
  actually applies — don't default to `manage_options` for things a
  lower-privileged role should legitimately be able to do).
- Escape on output, every time, using the context-correct function:
  `esc_html()`, `esc_attr()`, `esc_url()`, `esc_js()` — never raw-echo
  anything that traces back to user input or the database without one of
  these.
- Sanitize on input: `sanitize_text_field()`, `absint()`,
  `sanitize_email()`, etc. — appropriate to the expected shape of the
  data, applied at the point the `$_POST`/`$_GET` value is first read.
- `$wpdb->prepare()` for every query with a variable in it — no string-
  interpolated SQL, ever, no exceptions.

## Database tables

If a plugin needs its own tables (not just options), use `dbDelta()`:
```php
require_once ABSPATH . 'wp-admin/includes/upgrade.php';
$charset = $wpdb->get_charset_collate();
$sql = "CREATE TABLE {$wpdb->prefix}prefix_thing (...) {$charset};";
dbDelta($sql);
```
Track a `DB_VERSION` constant + a stored option so future plugin updates
can detect and re-run `dbDelta()` for schema changes.

## PHP 7.4 compatibility

Unless a specific brief says otherwise, target PHP 7.4+ (a large fraction
of real WordPress hosting is still on 7.4). Avoid PHP 8-only syntax
(named arguments, enums, readonly properties, `match`). If a codebase
needs `str_contains`/`str_starts_with`/`str_ends_with` (PHP 8.0+) on an
environment that might run 7.4, guard with `function_exists()`
polyfills rather than assuming they exist.

## Don't build what WordPress core already gives you

Before writing custom code for: cron scheduling (`wp_schedule_event`),
REST endpoints (`register_rest_route`), settings UI
(`register_setting`/`add_settings_field`/`woocommerce_admin_fields` if
WooCommerce context), object caching (`wp_cache_*` functions), HTTP
requests (`wp_remote_get`/`wp_remote_post`, not raw `curl`) — check
whether a core API already does it. Reinventing these is both wasted
effort and a common source of subtle bugs core already solved correctly.