Extending WPChangeSync

Manifest plus handler architecture

Integrations are plain configuration mapped onto generic handlers, not bespoke code. The handlers already know how to move options, custom database tables, post types, taxonomies, and post meta, so you describe what should be synced and the engine does the exporting, importing, and remote pushing.

The sync engine loads the active integrations, resolves each one to a handler, and gives them all the same behaviour: export, import, item listing, counts, storage path and filename, and whether the integration appears as a workflow option. That is why a third-party integration behaves identically to a built-in one in the Library and in workflows.

What an integration defines

An integration declares:

• An ID, label, category, and whether it is visible in the UI.
• Its handler type and the checks that decide when it is active.
• Its storage path and filename pattern.
• Whether it can be selected in workflows.
• Its default conflict-resolution behaviour.
• An exclude list, so licence keys, API tokens, and passwords never travel between sites. Common secret suffixes are filtered automatically as a safety net, but list yours explicitly.

The fastest way to write one is not to write one. Build it visually first as a custom source under Settings, then Data Sources, adding a part per data type. Then open that source's Export for developers panel and copy the finished JSON config or PHP snippet. The schema is identical, so you prototype without code and ship the result.

To register it from your own plugin you have two options: call wpchangesync_register_integration() on init, guarded with function_exists so your plugin still works when WPChangeSync is inactive, or ship *.json config files in a folder and announce it with the wpchangesync_integration_dirs filter. A detection rule keeps the integration hidden on sites where its data does not exist. The full schema is documented in docs/integration-api.md inside the plugin folder.

Extension points

The engine applies filters before export, fires actions at export start and batch lifecycle moments, and lets integration handlers own data-specific import/export logic. New integrations should keep payloads deterministic and Git-friendly.

If your framework stores attachment IDs in its own meta keys, add them to the media remapping pass with the wpchangesync_attachment_meta_keys filter. ACF image, gallery, and file fields are detected automatically, so this filter is how non-ACF field frameworks opt in.