wp-plugin-architecture

WordPress plugin: internal architecture

How the plugin organizes itself inside src/ once the bootstrap (see wp-plugin-bootstrap) and lifecycle (see wp-plugin-lifecycle) are in place. The bootstrap is the launcher; this skill is the engine layout.

Use src/ as the default PSR-4 root for new plugins. Treat includes/ and class-*.php filenames as legacy patterns to audit or migrate, not as a scaffold target.

Out of scope: bootstrap-file content, activation / deactivation / uninstall, cron specifics, REST endpoint design — covered by sibling skills.

When to use this skill

Trigger when ANY of the following is true:

• Scaffolding the src/ folder of a new plugin.
• Reviewing the class layout in a PR — folder structure, where things live, what's reused.
• Migrating old includes/class-my-plugin-foo.php files to Composer PSR-4.
• Deciding whether a meta key / option name belongs in a class const, a Schema.php, or a PHP enum.
• Reviewing asset enqueue code — wrong hook, missing dependencies, unconditional loading.
• The user asks "should this be a singleton" or "where should this constant live".

Folder layout — by-type or by-feature

Choose either by-type for a small cohesive plugin or by-feature when several domains evolve independently. Do not mix both schemes opportunistically. Across both styles, keep one class per PascalCase file and mirror the PSR-4 namespace path. Read references/layout-and-review-examples.md for both trees, migration signals, and a review comparison.

Composer mapping:

{
    "autoload": {
        "psr-4": {
            "MyPlugin\\": "src/"
        }
    }
}

Centralization — Schema / Constants is non-negotiable

Every string that appears more than once — meta key, option name, custom hook name, cron event name, CPT slug, capability slug, transient prefix — lives in one place. Three patterns that all work:

Class const on the feature class

class UsageTracker {
    public const OPTION_PREFIX = 'myplugin_usage_';

    public static function current_month_key(): string {
        return self::OPTION_PREFIX . gmdate( 'Y_m' );
    }
}