Plugin & Theme Update Validation

Overview

Extensions can participate in the update pipeline by validating whether an update is safe to apply. Validation runs during the extension verify stage (validate) and during core verify via extension_compat.

`ValidatesUpdate` interface

Implement on src/Plugin.php or src/Theme.php:

use App\Update\Contracts\ValidatesUpdate;
use App\Update\Pipeline\UpdateContext;
use App\Update\Reports\CheckResult;
use App\Update\Reports\StageReport;

class Plugin implements ValidatesUpdate
{
    public function validateUpdate(UpdateContext $context): StageReport
    {
        return new StageReport(
            stage: 'my_plugin_validation',
            status: StageReport::PASS,
            label: 'My Plugin',
            checks: [
                CheckResult::pass('tables_ready', 'Required tables exist'),
            ],
            message: 'Safe to update.',
        );
    }
}

Return StageReport::WARN to allow proceed-with-caution, or StageReport::FAIL to block the update.

Filter-based validation

add_filter('valpress_update_validate_my-plugin', function ($report, $context, $type) {
    if (!Schema::hasTable('my_plugin_queue')) {
        return new StageReport(
            stage: 'my_plugin_validation',
            status: StageReport::FAIL,
            label: 'My Plugin',
            checks: [
                CheckResult::fail('queue_table', 'Queue table missing'),
            ],
            message: 'Run migrations before updating.',
            actions: [
                \App\Update\Reports\RepairAction::repair('plugin_migrate', 'Run plugin migrations', ['slug' => 'my-plugin']),
            ],
        );
    }

    return $report;
}, 10, 3);

Scaffold command

php artisan vp:make-plugin-validation my-plugin

Uses the vp: prefix so ValPress commands stay separate from Laravel's built-in make:* generators.

Creates public/plugins/my-plugin/src/Plugin.php implementing ValidatesUpdate in the Plugins\{StudlySlug} namespace.

Reference example

A complete copy-pasteable plugin lives in the CMS repository at docs/1.x/examples/valpress-update-example/. Install it locally:

cp -r docs/1.x/examples/valpress-update-example public/plugins/valpress-update-example

On Windows (PowerShell):

Copy-Item -Recurse docs\1.x\examples\valpress-update-example public\plugins\valpress-update-example

It demonstrates migration checks, RepairAction buttons, and self-update warnings.

Core update participation

When verifying a core update, ValPress runs validators for:

All active plugins
Active theme(s), including child + parent

Critical extension failures block verification.

Extension self-update

When updating a plugin or theme through the Update Center, only the targeted extension is validated via validateTarget().