hirasso / wp-sync-deploy

3.0.3 2026-10-02 13:39 UTC

MIT

Published on Packagist.org on 2026-10-02 13:39 UTC

README

Sync and deploy your WordPress website between environments 🔀

• sync your WordPress database from production or staging to your local dev environment
• deploy your local core, plugins, mu-plugins and theme to production or staging
• run common tasks through wp-cli on the remote server to ensure your deploy works as expected
• tested on OSX and Linux systems

Note

For less technical users I recommend to use a plugin instead. For database migrations, I'd recommend WP Migrate. For deployment, I'd recommend good old (S)FTP.

Prerequesites

• WP-CLI installed on your local machine. On the remote server, wp-sync-deploy takes care of installing WP-CLI automatically.
• A WordPress directory structure similar to this (adjustable through a .env.wp-sync-deploy file):

.
├── content # your WordPress content folder (equivalent to the standard wp-content)
│  ├── plugins
│  ├── themes
│  ├── ...
├── core # your WordPress core folder (wp-admin, wp-includes, ...)
├── index.php # main WordPress entry file
└── wp-config.php # your wp-config file

Tip

While it's easy to setup the custom directory structure yourself, I'd recommend to use a framework like Bedrock, WPStarter or wordplate. All of these provide amazing convencience features for modern WordPress development.

Installation

composer require --dev hirasso/wp-sync-deploy

All commands are then available through a single binary:

vendor/bin/wp-sync-deploy <setup|sync|deploy|upload> [args]

Optionally, add script aliases to your project's composer.json:

"scripts": {
  "sync": "wp-sync-deploy sync",
  "deploy": "wp-sync-deploy deploy",
  "upload": "wp-sync-deploy upload"
},
"config": {
  "process-timeout": 0
}

…so that you can run composer deploy production run. The process-timeout prevents composer from aborting long-running syncs and deploys.

Warning

Composer silently drops options like --config or --paths that are passed to script aliases. Separate them with --:

composer deploy -- production run --config=.env.my-custom-config

Setup

Run this command:

vendor/bin/wp-sync-deploy setup

This will move the required configuration files to your current working directory and remove the .example part. You should now have these two files in your working directory:

.env.wp-sync-deploy

This file holds all information about your various environments (local, staging, production). Make sure you add .env.wp-sync-deploy to your .gitignore file! Otherwise, it's possible that sensitive information makes it into your repo.

VSCode can syntax highlight the env file for you.

wp-sync-deploy.tasks.php

This file is being used to run automated tasks after deployment. You can adjust this file as you wish or delete it if you don't want it to be executed.

Remote server preparation

wp-sync-deploy performs a few security checks before proceeding with a deploy:

• Do all directories marked for deployment actually exist in both environments (locally and remotely)?
• Does a hidden file .allow-deployment exist on the remote environment's web root?
• Does the local command-line PHP version match the one on the remote environment?
• Does the local web-facing PHP version match the one on the remote environment?

So when you are starting, you will need to

• Perform the first deployment manually (or via the upload command)
• Add an empty file .allow-deployment to your remote web root
• Make sure that your local and remote server are set to use the same PHP version

Usage

Synchronise the database between environments

# sync the database from your production server
vendor/bin/wp-sync-deploy sync production

# sync the database from your staging server
vendor/bin/wp-sync-deploy sync staging

# push your local database to your staging server
vendor/bin/wp-sync-deploy sync staging push

# Backup the remote database and store it locally
vendor/bin/wp-sync-deploy sync <production|staging> backup

Note

Syncing your local database is only possible to the staging server by default. If you are sure you know what you are doing, you can also enable syncing to the production server.

Deploy your local files to remote environments

# deploy your files to your production server (dry)
vendor/bin/wp-sync-deploy deploy production

# deploy your files to your staging server (dry)
vendor/bin/wp-sync-deploy deploy staging

# deploy your files to your production server (non-dry)
vendor/bin/wp-sync-deploy deploy production run

# deploy your files to your staging server (non-dry)
vendor/bin/wp-sync-deploy deploy staging run

Simple Upload

To make sure you are uploading to the correct directory, the remote directory needs to contain a file .allow-deployment

# Upload files to the remote root
vendor/bin/wp-sync-deploy upload <environment> --paths

# For example:
vendor/bin/wp-sync-deploy upload staging --paths=".env wp-cli.yml config public vendor"

Run automated tasks after each deploy / sync ✨

wp-sync-deploy will automatically run tasks on the target server when you sync or deploy. Modify the wp-sync-deploy.tasks.php file created by the setup command, to customize which tasks should be executed.

Default tasks defined in the file are:

• Optionally delete all transients
• Optionally delete your static cache
• When deploying: Optionally update the rewrite rules

Custom config file

By default, wp-sync-deploy looks for a .env.wp-sync-deploy file. You can override this with the --config option:

vendor/bin/wp-sync-deploy sync production --config=.env.my-custom-config
vendor/bin/wp-sync-deploy deploy production run --config=.env.my-custom-config
vendor/bin/wp-sync-deploy upload staging --paths="..." --config=.env.my-custom-config

Note

--config must come after the required positional arguments.

Other notes

wp-sync-deploy has a default list of files and directories that will be ignored during a deploy. If you wish to customize this list, copy the default .deployignore to your project root and adjust it there. It will then be used instead of the default one.

Before each run, wp-sync-deploy checks if an important update is available and asks for confirmation before proceeding with an outdated version.