WordPress Plugin Structure

When to use

• The user wants to organize plugin code with namespaces or autoloading and avoid function, class, or constant name clashes with other plugins.
• The user needs to run setup or teardown code on plugin activation, deactivation, or uninstall (create tables, flush rewrites, remove options).
• The user is starting a new WordPress plugin and needs the main plugin file, header, and directory layout.

When NOT to use

• Do not scaffold a full distributable plugin for a one-off single-site tweak; a code snippet or a small mu-plugin is enough.
• Do not build a plugin for theme-specific presentation such as templates, styles, or layout; put that in the theme or a child theme.

Core guidance

• Guard every PHP file against direct access — At the top of every plugin PHP file add defined('ABSPATH') || exit; so the file does nothing when requested directly over HTTP.
• Namespace all code or prefix every global symbol — Wrap plugin code in a PHP namespace such as namespace Acme\MyPlugin;, or if you must stay procedural, prefix every function, class, and constant with a unique vendor slug (for example acme_myplugin_init()).
• Clean up persistent data on uninstall, not deactivation — Remove options, custom tables, and scheduled events in uninstall.php (or a register_uninstall_hook callback), not in the deactivation hook.

Decision Engine

Walk this section before choosing an implementation path.

Is the code presentation tied to the theme, an always-on platform guardrail,
a distributed feature, or a one-off single-site tweak?

├── Must never be deactivated, no activation UI: → Ship an mu-plugin in `wp-content/mu-plugins` — it auto-loads, cannot be disabled
from the admin, but has no activation/deactivation hooks and no update UI.

├── User-facing feature, shipped or reusable: → Build a normal plugin with a full main-file header, activation/deactivation and
`uninstall.php` hooks, namespaced/autoloaded code, and an ABSPATH guard.

├── One hook, one site, never shipped: → Use a code snippet or a single-file mu-plugin — a full plugin skeleton (readme,
i18n, uninstall, autoloading) is overhead for one hook that never ships.

└── Templates, styles, layout for one theme: → Put it in the theme or a child theme, not a plugin — presentation should change
with the theme, and plugin features must survive a theme switch.

Full engine: references/decision-engine.md — Decision Tree, Priority Matrix, Decision Table.

Workflows

Workflow: Create Mu Plugin

Progress:
- [ ] Create `wp-content/mu-plugins/acme-platform.php`; a PHP file directly in
mu-plugins is auto-loaded on every request with no activation step
- [ ] Because WordPress only scans files directly in mu-plugins (not subfolders), have
the loader `require` your namespaced code from a subdirectory and boot it on
`plugins_loaded`

1. Create wp-content/mu-plugins/acme-platform.php; a PHP file directly in mu-plugins is auto-loaded on every request with no activation step.
   • Verify: The file's code runs on every request and the mu-plugin shows under the "Must-Use" tab.
2. Because WordPress only scans files directly in mu-plugins (not subfolders), have the loader require your namespaced code from a subdirectory and boot it on plugins_loaded.
   • Verify: Code in the subdirectory runs and stays organized under a namespace.

Workflow: Scaffold Plugin

Progress:
- [ ] Create `my-plugin/my-plugin.php` with a `Plugin Name:` header block (name,
version, `Requires PHP`, `Text Domain`) and `defined('ABSPATH') || exit;` on the
first line after the header
- [ ] Put classes under a namespace in `src/`, register a PSR-4 autoloader, and boot the
plugin from a callback on `plugins_loaded` rather than at file scope
- [ ] In the main file call `register_activation_hook(__FILE__, ...)` to create schema
and flush rewrites, `register_deactivation_hook(__FILE__, ...)` for reversible
teardown, and add `uninstall.php` to delete options and tables on removal

1. Create my-plugin/my-plugin.php with a Plugin Name: header block (name, version, Requires PHP, Text Domain) and defined('ABSPATH') || exit; on the first line after the header.
   • Verify: The plugin appears on the Plugins screen and direct access to the file returns nothing.
2. Put classes under a namespace in src/, register a PSR-4 autoloader, and boot the plugin from a callback on plugins_loaded rather than at file scope.
   • Verify: Classes resolve without manual requires and the plugin boots after WordPress is loaded.
3. In the main file call register_activation_hook(__FILE__, ...) to create schema and flush rewrites, register_deactivation_hook(__FILE__, ...) for reversible teardown, and add uninstall.php to delete options and tables on removal.
   • Verify: Activation sets up data, deactivation is reversible, and deleting the plugin leaves no orphaned rows.

Best practices

• Ship a normal plugin (activatable, distributable) by default; use an mu-plugin (wp-content/mu-plugins) only for must-use infrastructure that admins must never disable and that has no activation UI
• Load classes with a PSR-4 autoloader — Composer's vendor/autoload.php if you have dependencies, otherwise a small spl_autoload_register mapping your namespace to the src/ directory — instead of a wall of require calls
• Keep the main plugin file to the header, constants, the autoloader include, and hook registration; do the real work in classes loaded on plugins_loaded or init, not at file scope

Anti-patterns

See references/anti-patterns.md.

Debugging

1. Bundling Composer vendor without scoping — WordPress shares one PHP process, so the first plugin to autoload a class wins and the second plugin runs against an incompatible version, causing subtle failures or fatals. Fix: Scope bundled dependencies (for example with php-scoper) into your own namespace, or depend only on libraries unlikely to collide, so each plugin loads its own copy.
2. Registering activation hook from the wrong file — WordPress matches the hook against the main plugin file path, so a wrong FILE means activation setup never runs. Fix: Register activation, deactivation, and uninstall hooks in the main plugin file so __FILE__ resolves to the file WordPress activated, or pass the main file path explicitly.
3. Calling flush_rewrite_rules on every request — Flushing rewrites is expensive and, run per-request, adds noticeable latency to the whole site. Fix: Register post types and rewrites on init, but call flush_rewrite_rules() only inside the activation hook (and deactivation), never on the normal request path.
4. Loading the text domain too early — WordPress registers locale and translation infrastructure around init, so earlier calls no-op silently. Fix: Hook load_plugin_textdomain() to init (or later) so translations are loaded when they are ready.

Performance notes

• Calling flush_rewrite_rules on every request — Calling flush_rewrite_rules() on init (on every page load) instead of once in the activation hook rebuilds the rewrite rules on every request.

Production checklist

• Every PHP file starts with defined('ABSPATH') || exit; so it cannot run when hit directly.
• Classes are loaded through a PSR-4 autoloader rather than a list of require statements in the main file.
• Real work runs on plugins_loaded or init, not at file scope, so WordPress services are available.
• The main file declares Plugin Name, Version, Requires PHP, and a text domain in its header block.
• Activation sets up schema and flushes rewrites, deactivation is reversible, and uninstall.php removes persistent data.
• All functions, classes, and constants are namespaced or carry a unique vendor prefix to avoid collisions.

Version notes

• Requires PHP and Requires at least headers (PHP >=7.4) — The Requires PHP: and Requires at least: header fields let WordPress block activation on unsupported PHP or core versions; both are honored on current WordPress (6.7–6.8) and are the safe floor for a plugin targeting PHP 7.4–8.3.
• uninstall.php runs in a limited context (PHP >=7.4) — uninstall.php runs with the constant WP_UNINSTALL_PLUGIN defined but without the plugin's own code loaded, so it must be self-contained and guard on that constant; this behavior is stable across WordPress 6.x.

Security

• Block direct file access and keep secrets out of the tree — Guard every PHP file with defined('ABSPATH') || exit;, never place API keys or credentials in files under the web-served plugin directory, and validate and sanitize any input read during activation or uninstall.

Testing

• Activation and decision behavior are verified in eval/scenarios/wordpress/plugin-structure.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/decision-engine.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: wordpress/hooks-actions, wordpress/hooks-filters
Behavior constraints: ai-rules/strategy-minimal-diff

Skill contract

Produces: wp.plugin-scaffolded
Requires: stack.wordpress-site
Risk: low · Confidence: 0.9