Search by

gaambo / deployer-wordpress

fabiantodt

Deployer tasks for deploying WordPress Sites

Package info

github.com/gaambo/deployer-wordpress

pkg:composer/gaambo/deployer-wordpress

Security

Advisories: 0

Aikido package health analysis

Transparency log

Statistics

Installs: 1 028

Dependents: 0

Suggesters: 0

Stars: 48

Open Issues: 3

v5.0.0 2026-11-03 14:38 UTC

Requires

Requires (Dev)

Suggests

None

Provides

None

Conflicts

None

Replaces

None

MIT 1b2d0d1b0097994b68bdbff6fd6886c245fea147

  • Fabian Todt <fabian.woop@fabiantodt.at>

Published on Packagist.org on 2026-11-03 14:39 UTC

This package is auto-updated.

Last update: 2026-11-03 14:40:01 UTC

README

Deployer tasks and recipes for deploying WordPress sites. Supports simple rsync deployments, custom theme/plugin builds, and complex setups including Bedrock and multisite.

Table Of Contents

Installation

  1. composer require gaambo/deployer-wordpress --dev
  2. Copy example files from examples/simple/ or examples/bedrock/ to your project root
  3. Customize deploy.php and deploy.yml:
  • Set current_path for all hosts (remote + localhost)
  • Configure custom code as packages
  • Adjust deployment flow if needed
  1. Test on staging first, then deploy to production 🚀

This package requires the stable gaambo/deployer-utils:^1.0.1 release.

Requirements

  • PHP 8.3 or newer and Composer
  • Deployer 8 (automatically installed)
  • WordPress installation
  • *nix OS (Linux/macOS or WSL on Windows)
  • rsync installed

Optional (auto-installed on remote if missing):

  • WP-CLI for database tasks
  • Composer for package vendors (depending on your custom theme/plugins)
  • Node.js/npm for building assets (depending on your custom theme/plugins)

Upgrading from v4

See Upgrading from v4 in the changelog 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

Configure localhost in deploy.php:

localhost()
    ->set('public_url', 'http://wp-boilerplate.test')
    ->set('deploy_path', __DIR__)
    ->set('current_path', '{{deploy_path}}/public') // WordPress root
    ->set('dbdump_path', 'data/db_dumps')
    ->set('backup_path', __DIR__ . '/data/backups');

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 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 wp-config-local.php, which should be gitignored and created manually on each host. Require it from wp-config.php:

if (file_exists(__DIR__ . '/wp-config-local.php')) {
    require_once __DIR__ . '/wp-config-local.php';
}

Rsync filters

The default rsync config uses .deployfilter files for per-directory filtering. Place a .deployfilter file in your theme/plugin to exclude development files:

- phpcs.xml
- README.md
- .babelrc
- node_modules
- .eslintignore
- .eslintrc.json
- .stylelintignore
- .stylelintrc.json
- gulp.config.js
- gulpfile.babel.js
- package.json
- package-lock.json
- .babelrc
- phpcs.xml

This prevents any development files/development tools from syncing. I strongly recommend you put something like this in your custom theme and mu-plugins or overwrite any of the themes/filter or mu-plugins/filter configurations.

Tasks

Tasks are in the tasks/ directory. Run dep list to see all available tasks. See task source files for configuration options.

Database Tasks (tasks/database.php)

  • db:remote:backup: Backup remote database and download to localhost
  • db:local:backup: Backup local database and upload to remote host
  • db:remote:import: Import current database backup (from localhost) on remote host
  • db:local:import: Import current database backup (from remote host) on local host
  • db:push: Pushes local database to remote host (combines db:local:backup and db:remote:import)
  • db:pull: Pulls remote database to localhost (combines db:remote:backup and db:local:import)

Multisite support

For multisite installations, set wp/multisite to true to enable network-wide search-replace during database sync:

set('wp/multisite', true);

Packages system (tasks/packages.php)

Manage custom themes, plugins, and mu-plugins with individual build configs:

set('packages', [
    'custom-theme' => [
        'path' => '{{themes/dir}}/custom-theme',
        'remote:path' => '{{themes/dir}}/custom-theme', // optional
        'assets' => true,
        'assets:build_script' => 'build',
        'vendors' => true,              // Run composer install
    ],
    // Add more packages as needed
]);

Tasks:

  • packages:assets:vendors - Install npm dependencies
  • packages:assets:build - Run build scripts
  • packages:vendors - Install composer dependencies
  • packages:push / packages:pull - Sync packages

Other Task Categories

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)

  • wp:download-core, wp:push, wp:pull, wp:info

Languages (tasks/languages.php)

  • languages:push, languages:pull, languages:sync, languages:backup:*

Uploads (tasks/uploads.php)

  • uploads:push, uploads:pull, uploads:sync, uploads:backup:*

Legacy Tasks (use packages instead)

  • Themes: themes:push, themes:pull
  • Plugins: plugins:push, plugins:pull
  • MU-Plugins: mu-plugins:push, mu-plugins:pull

Recipes

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.

recipes/bedrock.php - Roots Bedrock projects with appropriate structure and environment handling.

Changelog

See CHANGELOG.md.

Contributing

Issues, feature requests, and pull requests welcome at GitHub. Code 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, 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.

CI tests Deployer 8 on PHP 8.3, 8.4, and 8.5.