Update Pipeline

Overview

ValPress updates run through a staged pipeline instead of a single opaque action. Each stage produces a structured StageReport with pass, warn, or fail status, optional checks, and repair actions.

The pipeline supports:

  • Core updates — full verify + apply flow with snapshot rollback
  • Extension updates — plugins and themes through a shorter dedicated flow

Architecture

ValPress 0.6 uses a staged pipeline for updates. The admin UpdateController is a thin HTTP adapter — it validates request input, delegates to services, and returns JSON for the Update Center UI. It does not contain download, migration, or file-copy logic.

HTTP (UpdateController)
  ├── GET  /admin/updates              → updates UI
  ├── GET  /admin/updates/check        → UpdateCheckService (api.valpress.net)
  ├── POST /admin/updates/run          → UpdatePipeline (verify_step / actual_step)
  ├── POST /admin/updates/repair       → RepairService
  ├── GET  /admin/updates/export-report → UpdateReportService
  └── snapshots restore/destroy        → SnapshotService
app/Update/
  Pipeline/          UpdateContext, UpdatePipeline, UpdatePipelineCatalog
  Stages/              Verify/, Apply/, Extension/ (one class per step)
  Services/            Dedicated services (see table below)
  Reports/             StageReport, CheckResult, RepairAction

Key services

Service Responsibility
UpdatePipeline Orchestrates verify/apply steps and aggregates stage reports
UpdateCheckService Queries ValPress API for core, plugin, and theme updates
UpdateApplyService Core file copy, production migrations, cache rebuild, finalize
ExtensionApplyService Extension download, extract, deploy, and version tracking
ExtensionUpdateService Fires post-update hooks only (update_plugin_{slug}, update_theme_{slug}, valpress_extension_updated)
ExtensionUpdateValidationService Resolves ValidatesUpdate implementations and filter-based validation
RepairService Executes whitelisted repair handlers from reports
SnapshotService Core file snapshots before apply; restore and delete
TestDatabaseService Dedicated test database configuration for verify simulation
UpdateReportService Structured, exportable JSON reports
UpdatePackageService Download and extract update archives
SimulationService Isolated copy and PHPUnit execution during verify
CompatibilityService PHP version, disk space, writable paths
UpdateHealthCheckService Routes, views, plugins, and site health during verify/apply

Extension apply finalize runs through ExtensionFinalizeStage, which calls ExtensionUpdateService::fireExtensionUpdatedHooks() — that service does not handle downloads or file deployment.

Wire protocol

HTTP and JavaScript use the catalog step field (e.g. init, download, health_check). Internal stage classes use a separate key (e.g. verify_init). Do not confuse the two.

Core verify stages

  1. init — prepare logs and test database
  2. download — fetch core archive
  3. extract — unpack to isolated directory
  4. prepare_env — configure test environment
  5. migrate — simulation migrations
  6. test — PHPUnit in isolated copy
  7. health_check — routes, views, plugins, site health
  8. extension_compat — active extension validators
  9. compare — detect modified core files

Core apply stages

  1. snapshot — pre-update file snapshot
  2. init — maintenance mode
  3. copy_files — deploy core files
  4. migrate — production migrations
  5. seed — optional seeders
  6. cache — rebuild caches
  7. post_verify — production health checks
  8. finalize — version bump, hooks, cleanup

On apply failure, core files are auto-restored from the snapshot when available.

Extension verify stages

  1. init
  2. download
  3. extract
  4. validate — ValidatesUpdate + filters
  5. migrate — extension migrations in test DB
  6. test — extension PHPUnit if present

Extension apply stages

  1. init
  2. download
  3. extract
  4. copy_files — deploy to public/plugins/{slug} or public/themes/{slug}
  5. migrate
  6. cache
  7. post_verify
  8. finalize

Extension apply does not create core snapshots or copy core files.

HTTP API

POST /admin/updates/run (requires manage_options)

Field Description
phase verify_step or actual_step
step Current pipeline step
type core, plugin, or theme
slug Required for extensions
version Target version

POST /admin/updates/repair

Field Description
repair_id Whitelisted repair handler id
repair_params Optional parameters (e.g. plugin slug)

Other Update Center routes: GET /admin/updates (UI), GET /admin/updates/check, POST /admin/updates/dismiss, GET /admin/updates/export-report, POST /admin/updates/snapshots/{id}/restore, DELETE /admin/updates/snapshots/{id}.

Hooks

Hook Purpose
valpress_update_verify_stages Add/reorder core verify stages
valpress_update_apply_stages Add/reorder core apply stages
valpress_update_extension_verify_stages Extension verify stages
valpress_update_extension_apply_stages Extension apply stages
valpress_update_health_checks Pipeline health checks
valpress_update_validate_{slug} Extension validation filter
valpress_update_repair_actions Register repair buttons
valpress_update_repair_handlers Register repair executors
valpress_update_pre_{phase} Before each step
valpress_update_post_{phase} After each step

Related docs