WPHammer
Log in
  • Related

    • Deployment Pipelines

    Every complex operation in WPHammer — creating a site, cloning one, restoring a backup — runs through a deployment pipeline. Each pipeline defines an ordered sequence of steps, and each step maps to a dedicated job. The system tracks progress in real time and handles failures gracefully.

    How pipelines work

    A pipeline implements the DeploymentPipeline interface, which requires two methods:

    • steps() — returns an ordered array of step definitions, each with a name and a job class
    • resolveJob(DeploymentStep $step) — creates the job instance for a given step, passing any required context from the deployment's meta data

    When a pipeline starts, WPHammer creates a Deployment record linked to the team, user, and site. Each step definition becomes a DeploymentStep record with a sort_order. The first step is dispatched immediately, and subsequent steps are dispatched sequentially as each one completes.

    Pipeline registry

    All pipeline types are registered in the PipelineRegistry during application boot. The registry maps a string type identifier to a pipeline class, so the Deployment model can resolve its pipeline dynamically via the type field.

    WPHammer ships with 13 pipeline types:

    Type Pipeline Steps Purpose
    create_site CreateSitePipeline 4 Create a new WordPress site on Forge
    clone_site CloneSitePipeline 8 Clone an existing site to a new server or location
    create_staging CreateStagingPipeline 6 Create a staging environment
    push_staging PushStagingPipeline 5 Push staging changes to production
    refresh_staging RefreshStagingPipeline 5 Refresh staging from production
    backup_site BackupSitePipeline 4 Run a full site backup
    restore_backup RestoreBackupPipeline 5 Restore from a backup
    create_snapshot CreateSnapshotPipeline 1 Create a server-local snapshot
    restore_snapshot RestoreSnapshotPipeline 1 Restore from a snapshot
    create_time_capsule CreateTimeCapsulePipeline 4 Create an off-site time capsule
    restore_time_capsule RestoreTimeCapsulePipeline 5 Restore from a time capsule
    restore_capsule_to_new_site RestoreCapsuleToNewSitePipeline 7 Restore a capsule to a different server
    download_capsule_archive DownloadCapsuleArchivePipeline 3 Download a capsule as a local archive

    Step execution

    Each step runs as a DeploymentStepJob on the queue. The base job class handles the lifecycle:

    1. Marks the step as Running with a started_at timestamp
    2. Calls the step's execute() method, which returns an output string
    3. On success, marks the step as Completed and dispatches the next queued step
    4. On failure, marks the step as Failed and the entire deployment as Failed
    5. If no more steps remain, the deployment is marked as Completed

    Both the Deployment and DeploymentStep models use BroadcastsEvents, so the UI updates in real time as each step progresses.

    Step statuses

    Each step tracks its own status via the StepStatus enum:

    • Queued — waiting to run
    • Running — currently executing
    • Completed — finished successfully
    • Failed — encountered an error
    • Skipped — bypassed (e.g., optional steps that do not apply)

    Pipeline examples

    Site creation

    The CreateSitePipeline runs four steps:

    1. Create database & user — provisions a MySQL database and user on the server via Forge
    2. Create WordPress site — creates the site in Forge with the correct PHP version and web directory
    3. Create custom domain — attaches the domain and configures DNS if needed
    4. Create tower-conf directories — sets up WPHammer's configuration directories on the server

    Site cloning

    The CloneSitePipeline extends site creation with backup and restore steps:

    1. Create database & user
    2. Create WordPress site on Forge
    3. Create custom domain
    4. Create tower-conf directories
    5. Backup source site — creates a backup of the site being cloned
    6. Transfer backup — copies the backup to the destination server
    7. Restore site from backup — applies the backup to the new site
    8. Clean up — removes temporary files from both servers

    Related