Skip to content

[00] Subset Sync, For developers

Developer reference

The WP-CLI commands, the hooks fired around a migration, and the settings you can lock from wp-config.php.

Everything the Subset Sync screen does is also a WP-CLI command, and every migration fires the same actions wherever it started. This page links to the commands, and lists the hooks and the wp-config.php constants.

WP-CLI

Every command lives under wp subset sync: push, pull, diff, export, import, backups, connections and, with Pro, file transfers and scheduled backups. WP-CLI commands lists each one with its options, defaults and examples.

When a migration finishes

<?php
add_action( 'wpmig_migration_finished', function ( string $event, array $summary ) {
	// $event is done, failed or cancelled.
}, 10, 2 );

It fires once per migration, whether it started in wp-admin or WP-CLI. $summary has the same shape every time:

KeyValue
idThe job’s ID.
intentpush, pull, export or import.
statusThe same as $event.
remoteThe other site’s URL, or null for an export or import.
started, ended, durationUnix timestamps, and the difference in seconds.
errorThe error a failed job stopped on, or null.
backupname, taken_at and remote for the backup taken first, or null.
tablesdone, total and rows, or null if no database moved.
mediadone, total, bytes and skipped, or null if no media moved.

wpmig_job_notification fires for migrations started in wp-admin, with the event (done, failed or stalled), the job’s progress and the WP_User to notify. Use it to send notifications somewhere other than email.

Hooks

HookTypeUse it to
wpmig_preserved_optionsfilterAdd options that stay with the destination when its database is replaced.
wpmig_before_swapactionRun on the destination right before the swap, while its own data is still live. Receives $tables and $swap_id.
wpmig_excluded_optionsfilterAdd options that never leave a site in any export, push, pull or backup.
wpmig_backups_to_keepfilterChange how many backups are kept. The default is 3.
wpmig_notify_afterfilterChange how long a job can stall before the email, in seconds. The default is 30 minutes.
wpmig_max_bodyfilterSet the largest request the destination accepts, in bytes. Match nginx’s client_max_body_size.
wpmig_network_mapfilterChange how a network’s subsites map onto the destination network.
wpmig_network_conversionfilterAllow a subdomain ↔ subdirectory migration. Defaults to false. Pro turns it on.

To keep your own plugin’s data across a pull:

<?php
add_filter( 'wpmig_preserved_options', function ( array $options ): array {
	$options[] = 'my_plugin_license_key';
	return $options;
} );

Admin screen hooks

wpmig_admin_tabs adds tabs (slug ⇒ label), and wpmig_admin_panel_{slug} fills each one. wpmig_admin_settings_rows adds rows to the Connection tab’s settings table, and wpmig_admin_backups_panel and wpmig_admin_settings_panel add a section to the end of the Backups and Connection tabs. wpmig_admin_enqueue fires after the screen’s own assets load.

Locking settings in wp-config.php

<?php
define( 'WPMIG_ALLOW_PUSH', false );
define( 'WPMIG_ALLOW_PULL', true );
define( 'WPMIG_IS_PRODUCTION', true );
define( 'WPMIG_VERIFY_SSL', true );

// Pro: accept pushed theme and plugin files.
define( 'SUBSET_MIG_PRO_ALLOW_FILES_PUSH', false );

A locked setting shows as disabled on the Connection tab, and wp subset sync allow refuses to change it. Nothing a migration or restore writes to the database can override it.