upsun-wp — the Upsun mu-plugin for WordPress

Platform integration for WordPress running on Upsun: environment awareness, router-cache friendliness, safe preview clones, deploy migrations, Cloudflare front-end support, Upsun-specific Site Health checks, and a wp upsun CLI command.

Site & docs: upsun.artetecha.com

The plugin detects Upsun at runtime (PLATFORM_APPLICATION_NAME + PLATFORM_ENVIRONMENT) and fully no-ops anywhere else — local development and CI need no special-casing. It reads platform variables directly and never defines WordPress configuration constants: your wp-config.php stays the single owner of database credentials, URLs, salts, and WP_ENVIRONMENT_TYPE.

This is a generic plugin for any WordPress project on Upsun; site-specific behavior belongs in the consuming project via the filters below — never in this package. It is used in production by two unrelated sites — an LMS/commerce site and a second migrated to the starter model at 1.0 — both consuming it exclusively through the public filter/constant API, which is what validates that the generic-vs-site-specific boundary holds. A companion starter repository — a deploy-ready Composer WordPress on Upsun, pre-wired for this plugin — is live.

Installation (Composer-managed WordPress)

Three steps: require the package, route the install path (and copy the loader shim), and wire the post_deploy hook.

1. Require the package

// composer.json
{
  "require": {
    "artetecha/upsun-wp": "^1.0"
  }
}

2. Route the install path and copy the loader shim. WordPress does not scan mu-plugin subdirectories, so a shim always has to reach the mu-plugins root; where the package itself may install depends on your layout.

Content directory OUTSIDE the core install dir (Bedrock-style): the standard route works — the package lands in mu-plugins/upsun/ (via its installer-name) and only the shim needs copying:

"extra": {
  "installer-paths": {
    "web/app/mu-plugins/{$name}": ["type:wordpress-muplugin"]
  }
},
"scripts": {
  "post-install-cmd": [
    "cp web/app/mu-plugins/upsun/upsun-loader.php web/app/mu-plugins/upsun-loader.php"
  ]
}

Content directory INSIDE the core install dir (johnpbloch-style wordpress/wp-content/...): do not route this package into wordpress/. Composer installs independent packages in alphabetical order; artetecha/* sorts before johnpbloch/*, and the WordPress core extraction replaces the entire install dir — silently deleting anything placed there earlier. Route the package to a staging directory and copy it in with the shim:

"extra": {
  "installer-paths": {
    "composer-mu-plugins/{$name}": ["artetecha/upsun-wp"],
    "wordpress/wp-content/mu-plugins/{$name}": ["type:wordpress-muplugin"]
  }
},
"scripts": {
  "postbuild": [
    "mkdir -p wordpress/wp-content/mu-plugins",
    "rm -rf wordpress/wp-content/mu-plugins/upsun",
    "cp -R composer-mu-plugins/upsun wordpress/wp-content/mu-plugins/upsun",
    "cp composer-mu-plugins/upsun/upsun-loader.php wordpress/wp-content/mu-plugins/upsun-loader.php"
  ],
  "post-install-cmd": "@postbuild",
  "post-update-cmd": "@postbuild"
}

(Add /composer-mu-plugins/ and the copied files to .gitignore; scripts run after every install, so the copy is always fresh.)

3. Wire preview sanitize into the post_deploy hook. Data syncs redeploy an environment without a code change, so only the post_deploy hook runs — deploy does not, which makes post_deploy the only hook that can catch every clone and resync. Add one line to .upsun/config.yaml that is safe on every environment (production refreshes the stamp that makes its clones detectable; already-sanitized previews no-op):

hooks:
  post_deploy: |
    wp upsun sanitize --if-needed

This line is also where your sanitization policy lives: --enable forces the opt-in DB-writing sanitizers for the run, so the whole policy is declared at project level in versioned config and applied identically to every child environment (or vary it per environment type with a small script):

hooks:
  post_deploy: |
    wp upsun sanitize --if-needed --enable="anonymize-user-emails,anonymize-user-passwords:password-{ID}"

Skipping this step does not weaken the runtime preview protections (mail interception, payment test mode, webhook pausing are active on every preview request from boot) — it only means the one-time upsun_preview_sanitize consumer actions never fire. The "Preview safety" health check (Site Health, the Upsun dashboard, wp upsun doctor) warns on every environment until the wiring is in place. If you cannot edit your hooks, enable the per-boot fallback via the upsun_safe_previews_boot_check filter.

Modules

Integrations

Everything the plugin knows about one specific third-party plugin lives in a dedicated class under src/Integrations/ — the single place to answer "what does this plugin do about X?". Integrations contribute exclusively through the same public filters consumers use (never privileged internal calls), so every built-in integration doubles as proof the public API is sufficient. They register at muplugins_loaded before regular plugins load; every contribution is a dormant no-op when its target plugin is absent, and the dashboard's Modules panel reports each integration's boot state plus whether the target was detected.

Toggles mirror modules: the upsun_integrations filter, or UPSUN_DISABLE_INTEGRATION_{ID} constants (e.g. UPSUN_DISABLE_INTEGRATION_WOOCOMMERCE, UPSUN_DISABLE_INTEGRATION_WP_ROCKET). To support a plugin the package doesn't know, use the public filters directly from your own mu-plugin — that is exactly what the built-in integrations do.

Configuration