[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:
| Key | Value |
|---|---|
id | The job’s ID. |
intent | push, pull, export or import. |
status | The same as $event. |
remote | The other site’s URL, or null for an export or import. |
started, ended, duration | Unix timestamps, and the difference in seconds. |
error | The error a failed job stopped on, or null. |
backup | name, taken_at and remote for the backup taken first, or null. |
tables | done, total and rows, or null if no database moved. |
media | done, 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
| Hook | Type | Use it to |
|---|---|---|
wpmig_preserved_options | filter | Add options that stay with the destination when its database is replaced. |
wpmig_before_swap | action | Run on the destination right before the swap, while its own data is still live. Receives $tables and $swap_id. |
wpmig_excluded_options | filter | Add options that never leave a site in any export, push, pull or backup. |
wpmig_backups_to_keep | filter | Change how many backups are kept. The default is 3. |
wpmig_notify_after | filter | Change how long a job can stall before the email, in seconds. The default is 30 minutes. |
wpmig_max_body | filter | Set the largest request the destination accepts, in bytes. Match nginx’s client_max_body_size. |
wpmig_network_map | filter | Change how a network’s subsites map onto the destination network. |
wpmig_network_conversion | filter | Allow 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.