README

About

A WP-CLI command for syncing a live site to a development environment.

This plugin works with both Roots Bedrock projects and vanilla WordPress installations. The project layout, uploads folder and WP-CLI binary are detected automatically, and can be overridden if needed.

By default the database and the uploads folder are synced on every project. On a vanilla project the plugins folder is pulled down too, since there's no composer file tracking what's installed. Bedrock projects keep their plugins under composer's control, so those are left alone. See Partial Syncs to sync just one part.

Requirements

Locally:

• A WordPress project, either bedrock based or vanilla
• WP-CLI
• rsync

On the live server:

• An SSH connection you can use without a password prompt
• WP-CLI, pointed at by REMOTE_WP_CLI if it isn't at vendor/bin/wp
• rsync

The plugin itself only ever runs locally, so there's nothing to install on the live server.

Installation

To install this plugin, follow these steps:

1. Require the plugin by running:

composer require jonbp/wp-cli-sync

On a vanilla project without composer, run this from the project root to fetch the latest release and write its loader:

curl -sSL https://raw.githubusercontent.com/jonbp/wp-cli-sync/master/install.sh | bash

Run it again whenever you want to update. Options are passed through with bash -s --, so bash -s -- --version=1.3.2 pins a release and bash -s -- --path=/path/to/project installs somewhere other than the current directory. See --help for the rest.

To do it by hand instead, drop the plugin into wp-content/mu-plugins/wp-cli-sync/ and load it with a wp-content/mu-plugins/wp-cli-sync-loader.php file containing:

<?php
require_once __DIR__ . '/wp-cli-sync/wp-cli-sync.php';

WordPress only loads PHP files sitting directly inside mu-plugins and doesn't look in subdirectories, so the loader is what makes the plugin's own folder work.

1. On a bedrock project, add the following to your .env file (don't forget .env.example for reference 😉):

# WP-CLI Sync Settings [wp sync]
LIVE_SSH_USERNAME=""
LIVE_SSH_HOSTNAME=""
LIVE_DOMAIN=""
REMOTE_PROJECT_LOCATION="~/gitrepo"

# Plugins should be formatted in a comma seperated format
# For example: "plugin1,plugin2,plugin3"

# Plugins activated on sync
DEV_ACTIVATED_PLUGINS=""

# Plugins deactivated on sync
DEV_DEACTIVATED_PLUGINS=""

On a vanilla project there's no .env file to read, so define the same names as constants in wp-config.php instead, above the wp-settings.php require:

/* WP-CLI Sync Settings [wp sync] */
define( 'LIVE_SSH_USERNAME', '' );
define( 'LIVE_SSH_HOSTNAME', '' );
define( 'LIVE_DOMAIN', '' );
define( 'REMOTE_PROJECT_LOCATION', '~/gitrepo' );

/* Plugins activated / deactivated on sync, comma seperated */
define( 'DEV_ACTIVATED_PLUGINS', '' );
define( 'DEV_DEACTIVATED_PLUGINS', '' );

Every variable in this README works either way. The environment is checked first, so an inline DEV_TASK_DEBUG=true wp sync still overrides whatever wp-config.php sets.

LIVE_DOMAIN is the live site's bare domain, such as example.com. Once it's set, the sync rewrites the database to dev.example.com afterwards, replacing every http, https, www and non-www variant of the live URL. Leave it empty to skip that step.

1. Run wp sync from the project root.

Partial Syncs

With no flags, wp sync syncs everything. To sync only part of the site, pass a flag:

--no-database and --no-media work the other way round, skipping that part and syncing the rest.

A media-only sync leaves the database alone, so the local site isn't put into maintenance mode while it runs.

First Sync

You may find yourself working on a bedrock project that already exists on a production server and you don't have the database setup locally yet. Running wp sync in the project will fail in this case as it requires an active WordPress installation to run.

To remedy this, you can run the following commands to create a database (if necessary) and create a basic installation inside that database in order to run the plugin and its first sync.

wp db create
wp core install --url=abc.xyz --title=abc --admin_user=abc --admin_password=abc --admin_email=abc@abc.xyz --skip-email

It’s not necessary to edit the variables on the second line as the database is overwritten by the plugin during sync. The code is simply to give the plugin the requirements it needs to run without the real database installed.

Extra Environment Variables

Below is a list of extra environment variables that can be added to your .env file to customise the sync process.

These can be set in your .env file or, on a vanilla project, as wp-config.php constants.