Theme framework: Updates

Coordinates parent-theme installation and version migrations.

Capabilities and extension points

Coordinates parent-theme delivery, installation, and migrations.

Migration registry.

• var Updates\Registry

Persistent lifecycle state.

• var Updates\State

Migration runner.

• var Updates\Runner

Parent package update checker.

• var Updates\Update_Checker

Migration registration failure for the current request.

• var \Throwable|null

Initializes update delivery and runs eligible pending migrations.

Migrations run before normal theme modules only in authorized non-AJAX admin requests, cron, and WP-CLI contexts.

Registers parent-owned migrations.

Add release migrations here. Class migrations are preferred for complex changes because they are easier to document and test:

$registry->add_class( Updates\Migrations\Feature_X::class );

A small migration may instead use callbacks. The update callback should preserve existing-site behavior with add_option(); the optional install callback can store the new-site default. Runtime feature code must use the legacy-safe fallback when the option is absent.

$registry->add( 'feature-x-default', '0.2.0', function ( $context ) { $context->add_option( 'cherry_blossom_feature_x', false ); }, function ( $context ) { $context->add_option( 'cherry_blossom_feature_x', true ); } );

Callback migrations also accept a fifth detection callback. It should inspect site state without mutating it and return whether the migration applies. Every released ID is immutable, and all migration behavior must be safe to retry after partial failure.

• param Updates\Registry $registry Migration registry.

Registers lifecycle hooks.

Registers WP-CLI migration commands when WP-CLI is active.

Displays failed-update and downgrade notices to administrators.

Gets the migration registry for diagnostics and automated tests.

Child themes must not register project migrations in this parent ledger.

• return Updates\Registry Migration registry.

Gets the migration runner for diagnostics and automated tests.

• return Updates\Runner Migration runner.

Source reference

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