Updates: Runner

Runs eligible migrations with locking and persistent progress tracking.

Capabilities and extension points

Classifies and processes parent-version transitions.

Maximum time a migration lock remains valid.

Atomic runner lock option.

• var string

Registered migrations.

• var Registry

Persistent lifecycle state.

• var State

Running parent version.

• var string

Migration registration failure for the current request.

• var \Throwable|null

Creates a migration runner.

• param Registry $registry Migration registry.
• param State $state Lifecycle state store.
• param string $current_version Running parent version.
• param \Throwable|null $registration_error Migration registration failure.

Processes a parent-version transition when required.

This method intentionally runs before normal theme modules. Migrations must remain small and idempotent because the eligible request executing them waits for them to finish. Automatic execution is limited by Updates to authorized non-AJAX admin requests, cron and WP-CLI.

• param bool $force Optional. Bypasses retry backoff and the current-version shortcut. Does not bypass locks or replay completed steps. Default false.
• return array { Transition result, including persisted state after this attempt.
• type string $classification Lifecycle classification, or locked.
• type bool $success Whether the attempt completed successfully.
• type array $state Stored lifecycle state. }

Gets the current lifecycle status for operational tooling.

• return array Lifecycle status.

Classifies the relationship between stored and running parent versions.

• param array $state Lifecycle state.
• return string Classification.

Resolves the operation retained by a failed run.

• param string $classification Current classification.
• param array $state Lifecycle state.
• return string Install or update operation.

Gets incomplete migrations eligible for the version transition.

Migration-specific applicability checks run later during execution.

• param string $operation Install or update operation.
• param string $from_version Previously completed parent version.
• return array Pending migrations.

Runs and records one migration.

Returning WP_Error from a callback is treated as a failure. Other return values are informational; throwing an exception also stops the sequence.

• param Interfaces\Migration $migration Migration instance.
• param Context $context Migration context.
• throws \RuntimeException When a migration returns WP_Error.
• throws \Throwable When a migration callback or lifecycle hook throws.

Determines whether an untracked site must be safely baselined.

Provisioning can explicitly identify a genuinely new site with the CHERRY_BLOSSOM_FRESH_INSTALL constant or the matching filter.

• param array $state Lifecycle state before this run.
• return bool Whether pending installation migrations should be baselined.

Marks migrations up to the running release as safely baselined.

Acquires a short-lived atomic migration lock.

• return bool Whether the lock was acquired.

Releases the migration lock.

Builds a consistent runner result.

• param string $classification Resulting classification.
• param bool $success Whether processing completed.
• return array Runner result.

Source reference

This editable reference page is based on the PHP documentation in updates/class-runner.php.