Hooks

View as Markdown Edit on GitHub Docs at 7a44bd6

Rudel fires WordPress actions and filters around sandbox lifecycle events. The catalog below is what Rudel::hooks() returns: 28 actions and 5 filters.

Example

PHP

add_action(
    'rudel_after_environment_create',
    function ( \Rudel\Environment $environment, array $context ): void {
        error_log( 'Created Rudel environment ' . $environment->id );
    },
    10,
    2
);

Most before and failed actions receive a $context array. For sandbox lifecycle hooks it holds the environment (or the name, options and environments_dir on create); failed actions also receive the caught Throwable as $error.

Sandbox lifecycle actions

Action	Arguments
`rudel_before_environment_create`	`$context`
`rudel_after_environment_create`	`$environment`, `$context`
`rudel_environment_create_failed`	`$context`, `$error`
`rudel_before_environment_update`	`$context`
`rudel_after_environment_update`	`$environment`, `$context`
`rudel_environment_update_failed`	`$context`, `$error`
`rudel_before_environment_destroy`	`$context`
`rudel_after_environment_destroy`	`$context`
`rudel_environment_destroy_failed`	`$context`, `$error`
`rudel_before_environment_replace_state`	`$context`
`rudel_after_environment_replace_state`	`$result`, `$context`
`rudel_environment_replace_state_failed`	`$context`, `$error`

The three replace_state actions belong to EnvironmentManager::replace_environment_state(), which no Rudel command calls.

Snapshot actions

Action	Arguments
`rudel_before_recovery_point_create`	`$context`
`rudel_after_recovery_point_create`	`$context`, `$meta`
`rudel_before_recovery_point_restore`	`$context`
`rudel_after_recovery_point_restore`	`$context`
`rudel_before_recovery_point_delete`	`$context`
`rudel_after_recovery_point_delete`	`$context`

$context holds environment, kind (snapshot), name and path. Each of these also fires under a snapshot alias, for example rudel_after_snapshot_create, and failures fire rudel_failed_recovery_point_{create|restore|delete} and rudel_failed_snapshot_{create|restore|delete} with $context and the error. Those aliases are not in the catalog.

Cleanup actions

Action	Arguments
`rudel_before_environment_cleanup`	`$options`
`rudel_after_environment_cleanup`	`$result`, `$options`
`rudel_before_environment_cleanup_merged`	`$options`
`rudel_after_environment_cleanup_merged`	`$result`, `$options`

$result holds removed, skipped, errors and reasons.

Git push actions

Action	Arguments
`rudel_before_environment_push`	`$context`
`rudel_after_environment_push`	`$sha`, `$context`
`rudel_environment_push_failed`	`$context`, `$error`

These fire for Rudel::push(). $context holds environment, remote, message and subdir. The wp rudel push command pushes directly and does not fire them.

Automation actions

Action	Arguments
`rudel_before_automation_cleanup`	`$config`
`rudel_after_automation_cleanup`	`$result`, `$config`
`rudel_after_automation_expiring_environments`	`$result`, `$config`

$config is the full rudel_config array. See Automation.

Filters

Filter	Arguments
`rudel_environment_create_options`	`$options`, `$name`, `$manager`
`rudel_environment_clone_source`	`$clone_source`, `$host_url`, `$db_cloned`, `$themes_cloned`, `$plugins_cloned`, `$uploads_cloned`, `$extra`
`rudel_environment_cleanup_options`	`$options`, `$repository`
`rudel_environment_cleanup_merged_options`	`$options`, `$repository`
`rudel_environment_db_dropin_contents`	`$contents`, `$context`

rudel_environment_create_options can change the options of any create call before Rudel acts on them. rudel_environment_clone_source filters the clone metadata stored on a sandbox created from the host. rudel_environment_db_dropin_contents applies only to the db.php drop-in that multisite-subsite environments use; overlay sandboxes, the only kind current versions create, never generate one.

Filters are intended for policy adjustment, not for replacing Rudel's storage model. Runtime identity, table prefixes, and worktree metadata remain DB-backed Rudel state.