v5: migrate shared helpers to deployer utils

.github/workflows/code-quality.yml

@@ -15,24 +15,15 @@ permissions:
 
 jobs:
   code-quality:
-    name: Run Code Quality Checks (PHP ${{ matrix.php }}, Deployer ${{ matrix.deployer }})
+    name: Code Quality (PHP ${{ matrix.php }}, Deployer 8)
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
       contents: read
       checks: write # needed for cs2pr to post inline annotations
     strategy:
       matrix:
-        include:
-          - { php: '8.2', deployer: '7.3' }
-          - { php: '8.2', deployer: '7.4' }
-          - { php: '8.2', deployer: '7.5' }
-          - { php: '8.3', deployer: '7.3' }
-          - { php: '8.3', deployer: '7.4' }
-          - { php: '8.3', deployer: '7.5' }
-          - { php: '8.3', deployer: '8.0' }
-          - { php: '8.4', deployer: '8.0' }
-          - { php: '8.5', deployer: '8.0' }
+        php: ['8.3', '8.4', '8.5']
       fail-fast: false
 
     steps:
@@ -52,13 +43,6 @@ jobs:
       - name: Validate composer.json
         run: composer validate --strict
 
-      - name: Set Deployer version constraint
-        env:
-          DEPLOYER_VERSION: ${{ matrix.deployer }}
-        run: composer require --no-update deployer/deployer:"${DEPLOYER_VERSION}.*"
-
-      # Install dependencies with caching — uses `composer update` (highest) so the pinned
-      # deployer constraint above is actually resolved.
       - name: Install Composer dependencies
         uses: ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda # v4.0.0
         with:

.github/workflows/tests.yml

@@ -18,18 +18,9 @@ jobs:
     timeout-minutes: 10
     strategy:
       matrix:
-        include:
-          - { php: '8.2', deployer: '7.3' }
-          - { php: '8.2', deployer: '7.4' }
-          - { php: '8.2', deployer: '7.5' }
-          - { php: '8.3', deployer: '7.3' }
-          - { php: '8.3', deployer: '7.4' }
-          - { php: '8.3', deployer: '7.5' }
-          - { php: '8.3', deployer: '8.0' }
-          - { php: '8.4', deployer: '8.0' }
-          - { php: '8.5', deployer: '8.0' }
+        php: ['8.3', '8.4', '8.5']
       fail-fast: false
-    name: Tests for Deployer ${{ matrix.deployer }} on PHP ${{ matrix.php }}
+    name: Tests for Deployer 8 on PHP ${{ matrix.php }}
 
     steps:
       - name: Checkout repository
@@ -44,23 +35,12 @@ jobs:
           php-version: ${{ matrix.php }}
           tools: composer:v2
 
-      # Pin the Deployer version constraint before installing, so the install
-      # step resolves the right version (and fails fast on invalid combos like
-      # PHP 8.2 + Deployer 8 which requires PHP ^8.3).
-      - name: Set Deployer version constraint
-        env:
-          DEPLOYER_VERSION: ${{ matrix.deployer }}
-        run: composer require --no-update deployer/deployer:"${DEPLOYER_VERSION}.*"
-
-      # Install dependencies with caching — uses `composer update` (highest)
-      # so the pinned deployer constraint above is actually resolved.
       - name: Install Composer dependencies
         uses: ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda # v4.0.0
         with:
           dependency-versions: highest
           composer-options: '--prefer-dist --no-progress'
 
-      # Run PHPStan so we check compatibility with the specified Deployer version.
       - name: Run PHPStan
         run: composer run-script phpstan
 

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Breaking Changes
 
+- PHP 8.3 or newer and Deployer 8 are now required. Deployer 7 support and compatibility code were removed.
+- Use Deployer's `quote()` directly instead of the removed `Utils::quote()` wrapper.
 - **`Files` path resolution**: Paths passed to `Files::pushFiles()` / `Files::pullFiles()` that begin with `/` are now
   treated as absolute rather than project-relative. Relative paths continue to resolve against `current_path` (local)
   or `release_or_current_path` (remote).
@@ -12,6 +14,7 @@
 
 ### Added
 
+- Local and remote WP-CLI and database commands can use runtimes supplied by `gaambo/deployer-utils`, including DDEV.
 - `Files::pushFile()` and `Files::pullFile()` helpers for transferring individual files with the same path resolution
   semantics as directory transfers.
 - `Files::resolvePath()` helper to resolve a path against a base path, leaving absolute and `~`-relative paths unchanged.
@@ -21,6 +24,16 @@
 - Database dump paths are now resolved consistently against `deploy_path` for WP-CLI export/import and file transfers,
   instead of being interpreted relative to different working directories.
 
+### Changed
+
+- Implemented [gaambo/deployer-utils#1](https://github.com/gaambo/deployer-utils/issues/1) by moving generic Composer,
+  npm, file, rsync, utility, localhost, runtime, test-support, and file-backup behavior to `gaambo/deployer-utils`.
+- WordPress tasks and recipes now use the shared helpers directly. Existing `Gaambo\DeployerWordpress` helper classes
+  remain as silent deprecated wrappers.
+- `files:push` and `files:pull` remain WordPress aggregate tasks. `files:backup:remote` and `files:backup:local` now load
+  from the shared package through the explicit utils task file.
+- Composer now uses the public `gaambo/deployer-utils:^0.1.1` release.
+
 ## v4.0.1 - 2026-04-28
 
 - Update composer packages

README.md

@@ -44,10 +44,12 @@ custom theme/plugin builds, and complex setups including Bedrock and multisite.
 
 4. Test on staging first, then deploy to production 🚀
 
+This package uses the public `gaambo/deployer-utils:^0.1.1` release.
+
 ## Requirements
 
-- PHP + [Composer](https://getcomposer.org)
-- [Deployer](https://deployer.org) (automatically installed)
+- PHP 8.3 or newer and [Composer](https://getcomposer.org)
+- [Deployer 8](https://deployer.org) (automatically installed)
 - WordPress installation
 - *nix OS (Linux/macOS or [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10) on Windows)
 - `rsync` installed
@@ -64,11 +66,7 @@ Example recipes (in `examples/`) provide configuration starting points. The libr
 vanilla, Composer, subdirectory, Bedrock, multisite) by making all paths and directories configurable. Check the example
 recipes and task source files for available options.
 
-### Localhost context
-
-Version 4 introduces a proper `Localhost` context. This ensures that when tasks run on your local machine
-(like building assets or backing up the local database), they use configuration values specifically defined for
-localhost, rather than falling back to global or remote values.
+### Localhost Context
 
 Configure localhost in `deploy.php`:
 
@@ -81,11 +79,14 @@ localhost()
     ->set('backup_path', __DIR__ . '/data/backups');
 ```
 
-The `Localhost` utility class (`Gaambo\DeployerWordpress\Localhost`) handles switching context automatically in tasks.
-
 `deploy_path` is the project root and is used for private data such as relative database dump paths. `current_path` is
 the WordPress root. The previous `project_path` example setting was unused and has been removed.
 
+Local and remote WP-CLI database commands honor runtimes configured on their source hosts and map database dump paths
+into them. See the
+[Deployer Utils README](https://github.com/gaambo/deployer-utils#readme) for generic localhost, runtime, Composer, npm,
+file, and rsync APIs. The old `Gaambo\DeployerWordpress` helper names remain as deprecated wrappers for migration.
+
 ### wp-config.php (Recommendation)
 
 Keep `wp-config.php` in git and deploy it. Extract environment-specific config (database credentials, `WP_DEBUG`) into
@@ -173,6 +174,7 @@ set('packages', [
 **File Tasks** (`tasks/files.php`)
 
 - `files:push` / `files:pull` - Sync all files (combines wp, uploads, plugins, themes, packages)
+- `files:backup:remote` / `files:backup:local` - Back up all files through the shared utils tasks
 
 **WordPress Core** (`tasks/wp.php`)
 
@@ -218,16 +220,4 @@ The library includes a comprehensive test suite with unit, integration, and func
 - Functional tests use a mocked environment to verify rsync commands and file operations without real remote
   connections.
 
-The library supports both Deployer v7 and v8. Test against both before submitting (note: Deployer v7 requires PHP 8.2 or 8.3 — it is incompatible with PHP 8.4+):
-
-```bash
-# Switch to Deployer v7
-composer require --no-update deployer/deployer:"7.5.*"
-composer update deployer/deployer --with-dependencies
-composer precommit
-
-# Switch back to v8
-composer require --no-update deployer/deployer:"^7.3 || ^8.0"
-composer update deployer/deployer --with-dependencies
-composer precommit
-```
+CI tests Deployer 8 on PHP 8.3, 8.4, and 8.5.

composer.json

@@ -14,13 +14,13 @@
     "phpstan/phpstan": "^2.1",
     "phpunit/phpunit": "^10.5",
     "squizlabs/php_codesniffer": "^3.11 || ^4.0",
-    "symfony/console": "^6.4 || ^7.4.0 || ^8.0.0",
-    "symfony/process": "^6.4 || ^7.4.0 || ^8.0.0"
+    "symfony/console": "^7.4.0 || ^8.0.0",
+    "symfony/process": "^7.4.0 || ^8.0.0"
   },
   "require": {
-    "php": "^8.2",
-    "composer-runtime-api": "^2.0",
-    "deployer/deployer": "^7.3 || ^8.0"
+    "php": "^8.3",
+    "deployer/deployer": "^8.0",
+    "gaambo/deployer-utils": "^0.2.0"
   },
   "autoload": {
     "psr-4": {
@@ -30,7 +30,7 @@
   "autoload-dev": {
     "psr-4": {
       "Gaambo\\DeployerWordpress\\Tests\\": "tests/",
-      "Gaambo\\DeployerWordpress\\PHPStan\\": "phpstan/",
+      "Gaambo\\DeployerUtils\\Tests\\": "vendor/gaambo/deployer-utils/tests/",
       "Deployer\\": "vendor/deployer/deployer/src/"
     }
   },
@@ -62,9 +62,7 @@
   },
   "config": {
     "allow-plugins": false,
-    "preferred-install": {
-      "*": "dist"
-    },
+    "preferred-install": "dist",
     "policy": {
       "advisories": {
         "audit": "report"