Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 4 additions & 20 deletions .github/workflows/code-quality.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,50 +15,34 @@ 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:
- name: Checkout repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# Do not store git credentials in .git -> could be leaked/exposed by infected/malicious action.
persist-credentials: false

# Setup PHP with Composer and cs2pr
- name: Setup PHP and tools
uses: shivammathur/setup-php@7c071dfe9dc99bdf297fa79cb49ea005b9fcadbc # v2.37.1
uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # v2.40.0
with:
php-version: ${{ matrix.php }}
tools: composer:v2, cs2pr

- 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:
Expand Down
10 changes: 6 additions & 4 deletions .github/workflows/composer-diff.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,14 +23,14 @@ jobs:
pull-requests: write # needed for sticky-pull-request-comment to post/update PR comments
steps:
- name: Checkout repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0 # Required for IonBazan/composer-diff-action
# Do not store git credentials in .git -> could be leaked/exposed by infected/malicious action.
persist-credentials: false

- name: Setup PHP and tools
uses: shivammathur/setup-php@7c071dfe9dc99bdf297fa79cb49ea005b9fcadbc # v2.37.1
uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # v2.40.0
with:
php-version: 8.3
tools: composer:v2
Expand All @@ -40,10 +40,12 @@ jobs:

- name: Generate composer.lock diff
id: composer-diff
uses: IonBazan/composer-diff-action@3140157575f6a67799cc80248ae35f5fb303ab15 # v1.2.0
uses: IonBazan/composer-diff-action@e2022e8718d05cc6e4e5990a06fc928c75837f76 # v2.0.0
with:
format: mdtable

- name: Post diff as sticky comment
uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v3.0.4
uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v3.0.5
# An empty diff result will break this action.
if: ${{ steps.composer-diff.outputs.composer_diff_exit_code != 0 }}
with:
Expand Down
28 changes: 4 additions & 24 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,49 +18,29 @@ 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
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# Do not store git credentials in .git -> could be leaked/exposed by infected/malicious action.
persist-credentials: false

- name: Setup PHP and tools
uses: shivammathur/setup-php@7c071dfe9dc99bdf297fa79cb49ea005b9fcadbc # v2.37.1
uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # v2.40.0
with:
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

Expand Down
93 changes: 92 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,29 @@
# Changelog

## Unreleased
## v5.0.0 - 2026-11-03

v5 moves shared helpers to Deployer Utils and adds runtime-aware WP-CLI commands.

### 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.
- `Utils::isDeployerVersion()`, `Utils::parseStringArray()`, and `Utils::parseStringOrNull()` were also removed.
Deployer 8 is now required, so remove version checks. The parsing helpers are internal to Deployer Utils' rsync
implementation; custom callers must handle their own value parsing.
- **`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).
- **Database dump paths**: Relative `dbdump_path` values now resolve against `deploy_path` instead of `current_path`.
Localhost must define `deploy_path`; the unused `project_path` example setting has been removed.
- **Local WP-CLI working directory**: `WPCLI::runCommandLocally()` now defaults to localhost's `current_path`.
Pass a different path explicitly, or `null` to use Deployer's `working_path` or the runtime's default directory.
- **Localhost runtime execution**: `Localhost::run()` now honors the configured runtime. Use
`Localhost::runNative()` when a custom task must run outside it.

### 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.
Expand All @@ -20,6 +32,85 @@

- 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.
- Shared file-backup tasks load from Composer's installed package path, including symlinked path repositories.
- Empty WP-CLI working-directory paths now behave like `null` rather than passing an invalid directory to the runner.

### 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, except for the removed `Utils` methods listed above.
- `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 requires the stable `gaambo/deployer-utils:^1.0.1` release.
- Updated Composer dependencies and SHA-pinned GitHub Actions.
- `composer precommit` now runs `composer validate --strict`, matching CI.

### Upgrading from v4

1. **Update dependencies**: Use PHP 8.3+ and update any explicit Deployer constraint to `^8.0`.
Review [Deployer's upgrade guide](https://deployer.org/docs/8.x/UPGRADE) for custom tasks.
Run:

```sh
composer require --dev gaambo/deployer-wordpress:^5.0 --with-all-dependencies
```

Deployer Utils installs automatically. If you require it directly, use `^1.0.1`.

2. **Set localhost paths**: Replace the unused `project_path` setting with `deploy_path` and make `current_path`
explicit. Adjust `public` to your layout; keep the WordPress root used by your existing simple/Bedrock recipe.

```php
localhost()
->set('public_url', 'https://example.test')
->set('deploy_path', __DIR__)
->set('current_path', '{{deploy_path}}/public')
->set('dbdump_path', 'data/db_dumps')
->set('backup_path', __DIR__ . '/data/backups');
```

Remote hosts also need `deploy_path` and `current_path`. This example stores dumps in
`<project>/data/db_dumps`, not `<project>/public/data/db_dumps`. Use an absolute `dbdump_path` to keep an existing
Comment thread
gaambo marked this conversation as resolved.
Resolved
location. With DDEV, even absolute dump paths must stay inside `deploy_path` so they can map into the container.
Keep dumps outside the public web root.

3. **Check custom file transfers**: Change `/wp-content/themes` to `wp-content/themes` if you meant a path below
the WordPress root, rather than an absolute filesystem path. File-transfer paths still use the WordPress root;
only relative database dump paths use `deploy_path`.

4. **Update helper imports**: Move `Composer`, `Files`, `Localhost`, `NPM`, `Rsync`, and `Utils` from
`Gaambo\DeployerWordpress` to `Gaambo\DeployerUtils`. The old imports remain deprecated wrappers without runtime
warnings, except for the removed `Utils` methods listed above. `WPCLI` stays in `Gaambo\DeployerWordpress`.
Replace `Utils::quote($value)` with:

```php
use function Deployer\quote;

$argument = quote($value);
```

Keep loading the WordPress recipes/task files; they already load the shared backup tasks and retain the
WordPress `files:push` and `files:pull` aggregate tasks.

5. **Check custom WP-CLI/runtime calls**: Pass an explicit working directory or `null` if a custom local WP-CLI
call should not use `current_path`. A `null` or empty path uses Deployer's `working_path`, if set, or the runtime's
default directory. For custom commands containing file paths, pass host-side paths to map:

```php
WPCLI::runCommandLocally(
"db export $dumpFile",
runtimePaths: [$dumpFile]
);
```

`runtimePaths` uses literal replacement throughout the command and arguments, not shell-token matching. Pass
full file paths and avoid overlapping paths or matching text that should not change.

Database tasks handle this mapping automatically. Runtimes are optional; without one, commands run on the host
as usual. For DDEV, keep dump paths below `deploy_path`. See the
[Deployer Utils runtime docs](https://github.com/gaambo/deployer-utils#runtimes) for PHP/YAML setup and path mapping.

## v4.0.1 - 2026-04-28

Expand Down
66 changes: 28 additions & 38 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,28 +9,20 @@ custom theme/plugin builds, and complex setups including Bedrock and multisite.
- [Table Of Contents](#table-of-contents)
- [Installation](#installation)
- [Requirements](#requirements)
- [Upgrading from v4](#upgrading-from-v4)
- [Configuration](#configuration)
- [Default Directory Structure](#default-directory-structure)
- [Localhost context](#localhost-context)
- [wp-config.php](#wp-configphp)
- [Rsync filters/excludes/includes](#rsync-filtersexcludesincludes)
- [wp-config.php](#wp-configphp-recommendation)
- [Rsync filters](#rsync-filters)
- [Tasks](#tasks)
- [Database Tasks (`tasks/database.php`)](#database-tasks-tasksdatabasephp)
- [Multisite support](#multisite-support)
- [Packages system (`tasks/packages.php`)](#packages-system-taskspackagesphp)
- [File Tasks (`tasks/files.php`)](#file-tasks-tasksfilesphp)
- [WordPress Tasks (`tasks/wp.php`)](#wordpress-tasks-taskswpphp)
- [Language Tasks (`tasks/languages.php`)](#language-tasks-taskslanguagesphp)
- [Uploads Tasks (`tasks/uploads.php`)](#uploads-tasks-tasksuploadsphp)
- [Legacy Tasks (Themes, Plugins, MU-Plugins)](#legacy-tasks-themes-plugins-mu-plugins)
- [WP-CLI](#wp-cli)
- [Recipes](#recipes)
- [Simple](#simple)
- [Bedrock](#bedrock)
- [Other Task Categories](#other-task-categories)
- [Recipes](#recipes)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Testing](#testing)
- [Built by](#built-by)

## Installation

Expand All @@ -44,10 +36,12 @@ custom theme/plugin builds, and complex setups including Bedrock and multisite.

4. Test on staging first, then deploy to production 🚀

This package requires the stable `gaambo/deployer-utils:^1.0.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
Expand All @@ -58,17 +52,18 @@ Optional (auto-installed on remote if missing):
- [Composer](https://getcomposer.org) for package vendors (depending on your custom theme/plugins)
- [Node.js/npm](https://nodejs.org/) for building assets (depending on your custom theme/plugins)

## Upgrading from v4

See [Upgrading from v4 in the changelog](CHANGELOG.md#upgrading-from-v4) before updating existing projects.
It covers PHP/Deployer requirements, helper imports, database and file paths, and WP-CLI runtimes.

## Configuration

Example recipes (in `examples/`) provide configuration starting points. The library works with any WordPress setup (
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`:

Expand All @@ -81,11 +76,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
Expand Down Expand Up @@ -173,6 +171,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`)

Expand All @@ -194,7 +193,7 @@ set('packages', [

## Recipes

v4 uses `current_path` for rsync-based deployments. Symlinked releases are still possible but not the default.
Like v4, v5 uses `current_path` for rsync-based deployments. Symlinked releases are still possible but not the default.

**`recipes/simple.php`** - Standard WordPress. Rsyncs directly to `current_path`. Recommended for most projects.

Expand All @@ -208,26 +207,17 @@ See [CHANGELOG.md](CHANGELOG.md).
## Contributing

Issues, feature requests, and pull requests welcome at [GitHub](https://github.com/gaambo/deployer-wordpress). Code
follows PSR-2 and Deployer best practices.
follows PSR-12 and Deployer best practices.

### Testing

The library includes a comprehensive test suite with unit, integration, and functional tests.

- Run `composer precommit` before submitting a PR — it runs lint, code style, PHPStan, and all tests.
- Run `composer precommit` before submitting a PR — it runs lint, code style, PHPStan, strict Composer validation,
and all tests.
- Functional tests use a mocked environment to verify rsync commands and file operations without real remote
connections.
- Tests load shared support classes from `deployer-utils/tests/` through `autoload-dev`. They rely on those files
shipping in Utils distribution archives, as documented in its shared test support API.

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.
Loading
Loading