WPHaven Connect

Note: This is the development documentation. WordPress plugins use readme.txt for their official plugin information and changelog, not this README.md file.

WordPress plugin that provides functionality to connect to the remote maintenance and management platform.

Features

• Development Mail Control: Block or redirect emails in non-production environments with SMTP override support
• Custom Admin Login URL: Hide default WordPress login URLs (wp-admin, wp-login.php) with custom slug (automatically bypassed on embold.dev and its subdomains so /wp-admin keeps working on dev)
• Error Monitoring: Centralized error handling and reporting to WP Haven platform
• Debug Notice Suppression: Automatically suppress textdomain and other development notices
• Magic Login Links: Generate secure one-time login URLs via WP-CLI for easier site access
• Environment Indicator: Visual admin bar badge showing current environment (development, staging, production)
• Elevated User Management: Restrict plugin, theme, and file management to specific admin emails
• Support Ticket Integration: Submit support tickets directly from WordPress dashboard
• Wordfence Integration: Automatic Wordfence alert forwarding to WP Haven platform
• WooCommerce Enhancements: Additional WooCommerce-specific functionality and monitoring
• Server & PHP Info API: Expose server and PHP configuration details via secure API endpoints
• Asset URL Fallback: Configure alternative asset URLs with ASSET_URL constant
• Haven WAF Cookie: Set security cookies for elevated users (admin/editor) for WAF bypass
• Content Transfer: Send an individual post/page/CPT to a chosen environment, or pull it back, from the editor. Copies custom fields (ACF, Yoast), terms, featured and inline images, authenticated by a shared secret that must match across environments. Also available in bulk — tick multiple items in the Posts/Pages/CPT list screens and push or pull them at once
• Compare: A read-only "Compare" tab showing how this environment diverges from another — table row counts, uploads totals, and per-post-type content divergence (how many posts/pages/products differ or exist on only one side)
• Multi-environment targets: A modular list of environments (production/staging/maintenance + extras) is the destination picker for all transfer tools; the app name auto-detects and the list can be populated from WP Haven
• Full Transfer: A one-click full Database + Uploads clone to/from a chosen environment (a "Full Transfer" tab), guarded by a per-direction typed phrase. Does not deploy code — deploy that separately
• Automatic Minor Core Updates: WordPress installs minor core releases (security/maintenance patches) on its own as soon as they ship, while major and dev releases stay manual (on by default, toggle in Core Updates). Since core is gitignored on our sites, it also stops WordPress treating the site as a VCS checkout — the detection that otherwise blocks all automatic updates
• Live Domain Swapping: On every save, other environments' URLs in post content and ACF fields are rewritten to this site's URL (on by default, toggle in Connection Settings); database syncs do the same across all known environment domains. Production media (ASSET_URL) is always left untouched
• Search & Replace: A "Search & Replace" tab for arbitrary, serialized-data-safe find/replace across selected tables, with a dry run that counts matches before committing
• Database Transfer: A settings-page tab to overwrite selected database tables between this environment and production (both directions), rewriting the source domain to the destination's (serialized-safe). Each table is backed up and swapped atomically; destructive actions require a typed confirmation phrase and run on non-production only
• Uploads Sync: A settings-page tab to additively sync the wp-content/uploads directory to/from production (both directions). Compares file manifests and transfers only what's missing (optionally also files that differ), chunking large files; never deletes; non-production only

Configuration

Configuration is available via:

1. WordPress Settings Page (Settings > WP Haven Connect):

   • Mail delivery mode (No Override, SMTP Override, Block All)
   • SMTP configuration (host, port, from address, from name)
   • Debug notice suppression
   • Custom notice strings to suppress
   • Elevated admin emails
   • WP Haven API base URL
   • Custom admin login slug
   • Enable automatic minor core updates (on by default)
   • A "Compare" tab showing divergence (table rows, uploads, per-post-type content differences) against a chosen environment
   • App name and a modular list of transfer environments (production/staging/maintenance + extras), with a "Populate from WP Haven" button
   • Environment connection secret (editable, with regenerate)
   • A "Database Transfer" tab for overwriting selected tables to/from a chosen environment
   • An "Uploads" tab for additively syncing the uploads directory to/from a chosen environment
   • A "Full Transfer" tab for a one-click Database + Uploads clone to/from a chosen environment
   • A "Search & Replace" tab for serialized-safe find/replace across selected tables (with dry run)

2. Environment Constants (in wp-config.php):

   • ELEVATED_EMAILS: Array of admin emails
   • DISABLE_MAIL: Block all mail when true (legacy, prefer mail_mode settings)
   • EMBOLD_SUPPRESS_LOGS: Suppress debug notices when true
   • WPH_ADMIN_LOGIN_SLUG: Custom admin login URL slug
   • WPH_DISABLE_LOGIN_BYPASS: Set to true to force login obfuscation even on embold.dev hosts
   • WPH_SHOW_ENVIRONMENT_INDICATOR: Show/hide environment indicator badge in admin bar
   • WPH_AUTO_CORE_MINOR_UPDATES: Enable/disable automatic minor core updates (and the VCS-checkout override that lets them run)
   • WPHAVEN_API_BASE: WP Haven API base URL
   • WPHAVEN_APP_NAME: This site's WP Haven name/slug (overrides the settings field; normally auto-detected)
   • WPHAVEN_PRODUCTION_URL: Production peer URL (overrides the "production" environment entry)
   • WPHAVEN_CONNECTION_SECRET: Environment connection secret; when defined it locks the settings field and disables editing/regeneration. Must be identical on every environment
   • EMBOLD_ALLOW_SVG: Enable/disable SVG uploads (if Embold Tweaks is also active)
   • EMBOLD_DISABLE_XMLRPC: Enable/disable XML-RPC blocking (if Embold Tweaks is also active)

Constants take precedence over plugin settings.

Example usage in wp-config.php:

define('ELEVATED_EMAILS', ['worf@embold.com', 'spock@embold.com']);
define('EMBOLD_SUPPRESS_LOGS', true);
define('WPH_ADMIN_LOGIN_SLUG', 'secret-login');

Custom Admin Login on Dev Domains

When a custom login slug is configured, the default /wp-admin and wp-login.php URLs are hidden (unauthenticated requests are redirected to a 404). To avoid having to remember a per-site login slug across internal environments, this obfuscation is automatically bypassed on embold.dev and any of its subdomains (e.g. webapp--adhealthpolicylab--xan.embold.dev) — on those domains /wp-admin and wp-login.php behave like a stock WordPress install. The custom slug still resolves as well, so existing links keep working.

To override this behavior:

• Set WPH_DISABLE_LOGIN_BYPASS to true in wp-config.php to force obfuscation even on an embold.dev host (useful for testing the real login flow).

• Use the wph_login_obfuscation_bypassed filter to extend the bypass to other hosts (e.g. .test or localhost):

  add_filter('wph_login_obfuscation_bypassed', function ($bypassed) {
      $host = $_SERVER['HTTP_HOST'] ?? '';
      return $bypassed || str_contains($host, '.test');
  });

Installation through git

From the wp-content/plugins directory:

git clone git@github.com:emboldagency/wphaven-connect.git && \
cd wphaven-connect && \
bash scripts/clean-dist.sh --yes && \
wp plugin activate wphaven-connect

scripts/clean-dist.sh strips the dev-only files listed in .distignore (including .git itself) so the installed copy matches what the release ZIP would have contained. As a safety check, it refuses to run against a git working tree that has uncommitted changes or unpushed commits — that's the signature of an active development checkout, not a fresh site install — so it won't accidentally wipe out .git in a repo you're actively working in. Run it with no arguments first to preview what would be removed; pass --force to bypass that check if you really mean to clean a dev checkout.

Development Setup

This project uses Docker Compose for local development.

Prerequisites

• Docker and Docker Compose
• Git

Getting Started

1. Clone the repository
2. Start the development environment:

   docker compose up -d

3. Access WordPress at http://localhost:8080

WP-CLI Usage

The project includes a persistent CLI container for easier package management:

# Start the CLI container (if not already running)
docker compose up cli -d

# Run WP-CLI commands
docker compose exec cli wp --info

# Install WP-CLI packages (they persist across restarts)
docker compose exec cli wp package install <package-name>

Building for Distribution

Automated Release via GitHub Actions

The plugin uses GitHub Actions to automatically create and publish releases:

How it works:

1. Create a new Git tag with semantic versioning:

   git tag 0.19.1
   git push origin 0.19.1

2. GitHub Actions automatically:

   • Runs the .github/workflows/release.yml workflow
   • Installs PHP, Composer, and WP-CLI
   • Installs the wp-cli/dist-archive-command
   • Creates a clean distribution ZIP file
   • Publishes it as a GitHub Release

3. The build creates this structure:

   dist/
   ├── archives/
   │   └── wphaven-connect-v0.17.0.zip  (WordPress-ready)
   └── extracted/
       ├── wphaven.php
       ├── src/
       └── ... (all plugin files)
   └── extracted/
   ├── wphaven.php
   ├── src/
   └── ... (all plugin files)

4. The ZIP archive is automatically available for:

   • Direct downloads from GitHub Releases
   • Distribution to WordPress.org plugin registry
   • Auto-update functionality via plugin-update-checker

Testing the workflow locally:

You can test the GitHub Actions workflow locally using act:

# Run the release workflow locally
act --workflows ".github/workflows/release.yml" --job dist

# The workflow will build and verify the archive without publishing

Manual Building to dist/ Directory

For local development builds without triggering a release:

Option 1: Development build (skip version checks)

composer run build:dev

Option 2: Production build (requires version match)

composer run build

• Verifies that wphaven.php version matches the latest Git tag
• Run composer run version:fix to auto-sync versions

Option 3: Using the Build Script Directly

./scripts/build.sh              # Check version and build
./scripts/build.sh --dev        # Skip version check (dev mode)
./scripts/build.sh --fix        # Sync versions and build

All methods:

• Extract version from wphaven.php
• Create a clean distribution archive using wp dist-archive
• Generate dist/archives/wphaven-connect-<VERSION>.zip
• Respect .distignore file for excluding development files

Requirements: WP-CLI on your PATH. Nothing else — no Docker, and no WordPress install, since wp dist-archive reads the plugin header and .distignore straight from this directory. The build installs the dist-archive command itself on first run, pinned to the same version CI uses so a local archive and a released one are built by identical code.

Note that vendor/ is tracked in this repo, so the build's --no-dev install temporarily strips your dev dependencies; the script reinstalls them when it finishes (skipped in CI, which throws its checkout away).

Build Output Structure

dist/
└── archives/
    └── wphaven-connect-v0.19.0.zip  (~186KB, WordPress-ready)

What Gets Excluded

The .distignore file excludes development files such as:

• .git/ directory and Git files
• node_modules/ and package management files
• composer.json and composer.lock
• Testing and build configuration files
• Documentation files like README.md
• Development scripts and Docker files

The resulting archive contains only the files needed for production WordPress installation.

Plugin Structure

• src/ - Main plugin source code
• vendor/ - Composer dependencies
• plugin-update-checker/ - Plugin update functionality
• readme.txt - Plugin readme/changelog
• wphaven.php - Main plugin entrypoint