Building SyncForge Config Manager: WordPress Config as YAML, Not Guesswork

SyncForge Config Manager is a WordPress plugin that treats configuration like code: export it to YAML, review diffs, import safely, and roll back when needed. It wires the same core engine into admin UI, REST, and WP-CLI, so workflows stay consistent across local, staging, and production.

The Problem

A DB dump is config management. It is mostly a panic button.

What breaks teams is configuration drift: options changed in wp-admin, theme mods changed in one environment, widget trees drifting silently, rewrite config different after one plugin update. Normal release pipelines do not track any of that cleanly.

"Export, import, and sync WordPress site configuration as YAML files across environments."

• SyncForge Config Manager README, GitHub

How It Works

The plugin boots a container, registers providers, then uses ConfigManager as the orchestration layer for export/import/diff/rollback. Providers define how each config domain maps between DB state and YAML files.

WP-CLI Path

real commands from src/CLI/*.php

wp syncforge export
wp syncforge diff --format=json
wp syncforge import --dry-run
wp syncforge import --yes
wp syncforge status
wp syncforge discover --track-all

REST/Admin Path

real routes from src/Rest/*.php

/wp-json/syncforge/v1/export
/wp-json/syncforge/v1/import
/wp-json/syncforge/v1/diff
/wp-json/syncforge/v1/snapshots
/wp-json/syncforge/v1/rollback/{id}
/wp-json/syncforge/v1/discover

Implementation

ConfigManager does the heavy lifting: lock acquisition, provider ordering (topological sort), YAML read, env override merge, schema validation, sanitization, then dry-run or import.

syncforge-config-manager/src/ConfigManager.php

private function do_import_provider( Provider\ProviderInterface $provider, bool $dry_run ): array {
	$config = $this->read_provider_config( $provider );

	$config = $this->container->get_environment_override()->apply_overrides( $provider->get_id(), $config );

	$validation = $this->container->get_schema_validator()->validate( $provider->get_id(), $config );

	if ( is_wp_error( $validation ) ) {
		throw new \RuntimeException(
			sprintf(
				esc_html__( 'Validation failed for provider %1$s: %2$s', 'syncforge-config-manager' ),
				esc_html( $provider->get_id() ),
				esc_html( $validation->get_error_message() )
			)
		);
	}

	$config = $this->container->get_yaml_sanitizer()->sanitize( $config, $provider->get_id() );

	if ( $dry_run ) {
		return $provider->dry_run( $config );
	}

	return $provider->import( $config );
}

Option discovery avoids hardcoded plugin lists. It classifies by patterns and groups discovered keys by plugin slug (or misc when ownership is ambiguous).

syncforge-config-manager/src/Admin/OptionDiscovery.php

private const RUNTIME_KEYWORDS = array(
	'_version',
	'_db_version',
	'_migration',
	'_nonce',
	'_session',
	'_token_',
	'_count',
	'_dismissed',
	'_telemetry',
	'_last_run',
	'_children',
	'_site_health',
);

private const RUNTIME_SUFFIXES = array(
	'_state',
	'_rat',
	'_pubkey',
	'_auth',
	'_install',
);

Provider ID	Dependency	File strategy
options	none	fixed files (options/general.yml, etc.) + dynamic extra groups
roles	none	dynamic directory (roles/{role}.yml)
menus	options	directory (menus/)
widgets	options	directory (widgets/)
theme-mods	options	single file (theme-mods.yml)
rewrite	options	single file (rewrite.yml)
block-patterns	none	directory (block-patterns/)

A real project change that matters: the rename from generic config-sync branding to syncforge-config-manager, reflected in plugin header and docs.

-=== Config Sync ===
+=== SyncForge Config Manager ===
-Contributors: victorstack-ai
+Contributors: victorjimenezdev
-Text Domain: config-sync
+Text Domain: syncforge-config-manager
-Plugin Name: Config Sync
+Plugin Name: SyncForge Config Manager

Supplementary: security controls implemented in code

• FileHandler::resolve_safe_path() rejects traversal before file access.
• ZIP import rejects entries containing .. and only extracts .yml.
• YamlSanitizer rejects serialized object payload patterns.
• AuditLogger redacts secret-looking keys before storing snapshots/diffs.
• Config directory gets .htaccess, index.php, and web.config deny files.

What I Learned

• Provider contracts beat one giant "sync everything" routine. Dependencies are explicit and sortable.
• The lock model (config_sync_lock in wp_options) is simple and good enough for admin/CLI concurrency.
• The same orchestration layer serving REST, CLI, and admin reduces edge-case drift in behavior.
• Default path choices matter more than people admit; the code defaults to wp-content/syncforge-config-manager, while docs still mention wp-content/config-sync/.

Use Dry-Run as a Release Gate

Make wp syncforge diff and wp syncforge import --dry-run mandatory in staging before any production import. The plugin already has the primitives; the missing part is process discipline.

Capability Model Is Split

REST checks manage_config_sync, while parts of admin/ZIP handling check manage_options. If this runs in a delegated ops model, unify capability checks to avoid "works in one interface, blocked in another" support drama.

References

• View Code
• Project README
• Main Plugin Bootstrap

---

Looking for an Architect who does not just write code, but builds the AI systems that multiply your team's output? View my enterprise CMS case studies at victorjimenezdev.github.io or connect with me on LinkedIn.