---
name: wp-rocket-architecture
description: Use this skill when changing service structure, Subscribers, ServiceProviders, Container wiring, bootstrapping, Context classes, or any code that may affect the core caching engine in WP Rocket. Also use it when reading constants, writing unit tests that depend on constants, or opening a pull request.
---

# 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

```php
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

```php
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

```php
// ❌ 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

```php
// ❌ 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 );
```

## Constants — read through `rocket_get_constant()`

Read WordPress and WP Rocket constants with `rocket_get_constant()`, cast to the type the code expects, with a default that matches WordPress core. Raw constants can't be changed per test, and their value types vary by WordPress version and wp-config (for example, `COOKIE_DOMAIN` is `false` before WP 6.6 or when defined as `false`).

```php
// ❌ Not mockable, and a TypeError when the constant isn't a string
$this->set_cookie( $name, $value, $expire, COOKIEPATH, COOKIE_DOMAIN, $secure, true );

// ✅ Required
$cookie_path   = (string) rocket_get_constant( 'COOKIEPATH', '/' );
$cookie_domain = (string) rocket_get_constant( 'COOKIE_DOMAIN', '' );
```

In unit tests, don't `define()` constants, use `@runInSeparateProcess`, or stub `rocket_get_constant` yourself. The base `TestCase::setUp()` already stubs it (`tests/StubTrait.php`), and it returns values from `$this->constants`. Set only the keys the test needs, and never replace the whole array:

```php
// ❌ Wipes out keys set by the base test setup
$this->constants = [ 'COOKIE_DOMAIN' => false ];

// ✅ Required
$this->constants['COOKIE_DOMAIN'] = false;
```

## PHPStan custom rules — all must pass

| Rule | Implication |
|---|---|
| `DiscourageApplyFilters` | Use `wpm_apply_filters_typed()` |
| `DiscourageWPOptionUsage` | Use `Options_Data` injection |
| `EnsureCallbackMethodsExistsInSubscribedEvents` | Implement every method you declare in `get_subscribed_events()` |
| `NoHooksInORM` | No `add_action`, `add_filter`, `apply_filters` inside `Database/Tables/` or `Database/Queries/` classes |

## 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

```php
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`.

## Pull request descriptions

Every PR body must follow `.claude/skills/issue-workflow/refs/pr-template.md` with its section headings copied exactly, including "What was tested" and "Mandatory Checklist". This applies outside the issue workflow too. The `PR Template Checker` CI (`wp-media/pr-checklist-action`) fails otherwise. Full rules are in `.github/instructions/pull-request.instructions.md`.