wp-rocket-architecture

WP Rocket Architecture Integrity

Enforce architectural patterns and protect internal service structure.

Core principles

• Every WordPress hook goes through a Subscriber — never add_action / add_filter directly.
• Every new filter uses wpm_apply_filters_typed() — never apply_filters().
• Plugin settings are read via injected Options_Data — never get_option().
• All instantiation goes through the League Container — never new ClassName() in business code.
• Do not modify inc/Dependencies/ (Mozart-bundled vendored code).

Subscriber pattern

class MySubscriber implements Subscriber_Interface {
    public static function get_subscribed_events(): array {
        return [
            'init'             => 'on_init',                      // priority 10, 1 arg
            'save_post'        => [ 'on_save_post', 10, 2 ],     // priority 10, 2 args
            'admin_menu'       => [
                [ 'add_menu',    9 ],
                [ 'add_submenu', 10 ],
            ],
        ];
    }
}

PHPStan enforces this: every method name in get_subscribed_events() must exist in the class (EnsureCallbackMethodsExistsInSubscribedEvents). Always implement the method before or alongside declaring it.

ServiceProvider pattern

class ServiceProvider extends AbstractServiceProvider {
    protected $provides = [ 'my_subscriber', 'my_controller' ];

    public function register(): void {
        $this->getContainer()->addShared( 'my_controller', Controller::class )
            ->addArguments( [ 'options', 'logger' ] );         // string = container key

        $this->getContainer()->addShared( 'my_subscriber', MySubscriber::class )
            ->addArgument( 'my_controller' );
    }
}

• addShared() → singleton (same instance every get() call)
• add() → factory (new instance every call)
• String arguments are container keys; use new StringArgument('...') for literal strings, new ArrayArgument([...]) for literal arrays.

Context classes

Features that are conditionally active encapsulate that logic in a Context class rather than inlining checks in the Subscriber:

inc/Engine/MyFeature/
└── Context/
    └── Context.php   // should_run(): bool — inject into Subscriber

The Subscriber calls $this->context->is_allowed() (or similar) as a guard clause. This keeps the Subscriber clean and the condition unit-testable in isolation.

wpm_apply_filters_typed() — mandatory for all new filters

// ❌ Flagged by PHPStan (DiscourageApplyFilters)
$value = apply_filters( 'rocket_my_filter', $default );

// ✅ Required — with full docblock
/**
 * Filters the custom value.
 *
 * @param string $value The value.
 * @return string
 */
$value = wpm_apply_filters_typed( 'string', 'rocket_my_filter', $default );

Available types: 'string', 'integer', 'boolean', 'array', 'string[]'.

Option objects — mandatory for reading plugin settings

// ❌ Flagged by PHPStan (DiscourageWPOptionUsage)
$setting = get_option( 'wp_rocket_settings' );

// ✅ Required — inject Options_Data via constructor (PHP 7.3+ compatible)
/** @var Options_Data */
private $options;

public function __construct( Options_Data $options ) {
    $this->options = $options;
}

$setting = $this->options->get( 'option_key', $default );

PHPStan custom rules — all must pass

Standard module directory structure

inc/Engine/MyFeature/
├── ServiceProvider.php          # all bindings + declares $provides
├── Context/
│   └── Context.php             # feature availability guard
├── Admin/
│   └── Subscriber.php          # admin-only hooks
├── Frontend/
│   ├── Controller.php          # business logic
│   └── Subscriber.php          # frontend hooks
└── Database/                   # only when custom tables are needed
    ├── Tables/MyFeature.php    # BerlinDB schema, version YYYYMMDD
    ├── Queries/MyFeature.php   # query builder
    ├── Rows/MyFeature.php      # row model
    └── Schemas/MyFeature.php   # column definitions

BerlinDB table versioning

protected $version = 20251006;  // YYYYMMDD
protected $upgrades = [
    20251006 => 'add_new_column',
];
protected function add_new_column(): void {
    // ALTER TABLE with $wpdb->prepare
}

Structural guardrails

Avoid:

• Global state or new singletons outside the container
• Static helpers replacing injected services
• Business logic inside ServiceProvider register() — wiring only
• Hooks or filters inside Database/Query/Table classes (NoHooksInORM)

Git Operations

Follow the policy defined in AGENTS.md §5.1. Outside the issue workflow, do not run git commit or git push.