WellTend Snapshots is built so other code can extend it. Everything it handles is a provider: a registered source of settings. The filter that collects providers is a public API.
Add your own provider#
This registers a source for a fictional plugin, "Acme Forms". It was run against a real site; the output is shown below.
use AllWPCare\SiteConfigManager\Providers\Provider;add_filter( 'awc_scm_providers', function ( array $providers ) { $providers[] = new Provider( array( 'id' => 'plugin.acme-forms', 'label' => 'Acme Forms', 'schema' => array( 'acme_settings' => array( 'type' => 'array', 'label' => 'Acme Forms settings' ), 'acme_mode' => array( 'type' => 'enum', 'label' => 'Mode', 'options' => array( 'live', 'test' ) ), ), 'secret_keys' => array( 'acme_settings.webhook' ), 'ignore_keys' => array( 'acme_settings' => array( 'last_sync' ) ), 'available' => static function () { return defined( 'ACME_FORMS_VERSION' ); }, 'version_constant' => 'ACME_FORMS_VERSION', ) ); return $providers;} );With the options acme_settings and acme_mode stored, wp awc config export --sources=plugin.acme-forms produces:
"source_versions": { "plugin.acme-forms": "2.4.0"},"sources": { "plugin.acme-forms": { "acme_mode": "test", "acme_settings": { "from_email": "hello@example.com", "notify": true, "webhook": "__awc_redacted__" } }}The webhook value is redacted because it is listed in secret_keys, and last_sync is left out because it is listed in ignore_keys. Import and restore then work for your source with no more code: values are validated against your schema, secrets are kept, and your source is skipped if Acme Forms is not active.
Provider configuration#
Provider is the generic option-backed provider. These keys are accepted:
| Key | Purpose |
|---|---|
id, label | Required. The id is unique and dotted; ids starting core. and theme.mods are exempt from the version check. |
schema | Setting name to type and label (plus options for enums). Only settings listed here are ever read or written. |
secret_keys | Names or dotted paths that are always redacted. |
safe_keys | Names, dotted paths or /regex/ entries exempt from the secret-name pattern. |
environment_keys | Settings left out unless environment settings are requested. |
ignore_keys | Option name to a list of top-level keys that are runtime state: never exported, preserved on write. |
available | A callable or boolean. When it returns false, the source is not exported and is skipped on restore. |
version_constant or version | The version recorded in source_versions, from a constant name, a string or a callable. |
getter, setter | For settings that are not plain options. getter( bool $include_env ) returns an array of values; setter( array $values ) writes and returns the keys written. |
current_getter | Returns the live, unredacted values; used on write to resolve markers and keep secrets. |
Types you can use in a schema: string, int, float, bool, yesno, enum, email, url, array, mixed. A schema entry can also carry validate (a callable returning an error message or null), risky => true (adds a security warning on change), and exists as post, term or attachment (the value is an id that must exist on the target).
For full control, implement AllWPCare\SiteConfigManager\Providers\ProviderInterface yourself: get_id, get_label, get_schema, get_secret_keys, get_safe_keys, get_environment_keys, is_available, get_version, read, write and get_skip_reason. Items in the filtered list that do not implement the interface, or have an empty id, are discarded.
Selectors such as --sources=plugin match the id prefix, so a well-chosen dotted id makes your source selectable as a group.
Hooks#
| Hook | Type | Arguments | Fires |
|---|---|---|---|
awc_scm_providers | filter | ProviderInterface[] $providers | When the provider list is built. Return the list. |
awc_scm_max_import_bytes | filter | int $bytes | When an import file is checked. Default 5,242,880. |
awc_scm_before_snapshot | action | string $origin, string $label | Before a snapshot of the current site is taken. |
awc_scm_after_snapshot | action | int $id, ?array $snapshot | After a snapshot is stored, including safety copies. |
awc_scm_before_restore | action | array $plan | After validation and planning, before the safety copy and any write. Only fires when there is something to apply. |
awc_scm_after_restore | action | array $report | After a restore or import. Also fires when nothing needed to change. |
$report holds snapshot_id, applied, skipped, unchanged, warnings and total_changes.
The helper awc_scm_is_pro() returns whether a valid Pro licence is active. It always returns false in the free build.
Settings for a tweaks plugin#
WellTend Snapshots has no modules of its own. It reads and restores settings that other plugins register as sources. WellTend Site and Admin Toolkit does exactly that: one toolkit.<module id> source per module, registered through awc_scm_providers with a schema for readable labels and secretKeys for passwords and API keys. Use the same filter for your own plugin.
REST API#
Namespace awc-scm/v1. Every route requires the manage_options capability. In the dashboard that means the logged-in cookie and an X-WP-Nonce header; from outside, use any WordPress REST authentication that identifies an administrator, such as an application password.
| Route | Method | Purpose |
|---|---|---|
/providers | GET | Every provider: id, label, available, version, environment_keys, schema. |
/settings | GET, POST | Plugin settings: retention (1 to 1000) and delete_data. |
/snapshots | GET | List. Parameters per_page (default 50, max 200), page, origin. Total count in the X-WP-Total header. |
/snapshots | POST | Create a manual snapshot. Parameters label, sources, include_env. Returns 201. |
/snapshots/<id> | GET, DELETE | Read a snapshot including its document, or delete it. |
/snapshots/<id>/export | GET | Download the snapshot as JSON. |
/export | GET | Download the current settings as JSON. Parameters sources, include_env. |
/import/preview | POST | Dry run of an import. Body document (object) or json (text), plus sources, include_env, force. |
/import/apply | POST | Apply an import, with a safety copy labelled "Before import". Same body. |
/restore/preview | POST | Dry run of a restore. Body snapshot_id (required), sources, include_env, force. |
/restore/apply | POST | Restore a snapshot. Pass a safety copy's id to undo. Same body. |
/diff | POST | Compare. Body a (required) and b (default current), each "current", a snapshot id, or an object with document; optional sources. |
Previews return the plan: valid, errors, warnings, providers (each with status of apply, unchanged or skip, plus changes and redacted), total_changes and will_change. Applies return the report. Invalid imports return a 400 with the first error message. A missing snapshot returns 404 with the code awc_scm_snapshot_not_found.
Downloads (/export, /snapshots/<id>/export) serve the exact canonical JSON bytes, the same ones the command line writes.
Storage#
- Table
{prefix}awc_scm_snapshots: see Snapshots. - Options:
awc_scm_settings(retention, delete on uninstall),awc_scm_db_version. - Constants:
AWC_SCM_VERSION,AWC_SCM_FORMAT_VERSION(the export format, currently 1), andAWC_SCM_FILE,AWC_SCM_DIR,AWC_SCM_URL. - Multisite: the plugin works per site. There are no network-admin features in this version.