WP Staging Restore Tool - Filter Configuration • WP STAGING

The standalone restore tool supports customizing restore behavior through a JSON configuration file. This provides filter-based customization similar to the WordPress plugin, but without requiring WordPress to be running.

Note: If no wpstg-restore-config.json file exists, the restore tool runs with its normal default behavior.

How It Works

Place a file named wpstg-restore-config.json in the same directory as wpstg-restore.php.
The tool reads the config on startup and applies the filter values during restore.
If no config file exists, the tool behaves as usual using all defaults.

Config File Format

{
  "version": 1,
  "filters": {
    "filter.name": "value"
  }
}

version: Schema version. Must be 1.
filters: Object mapping filter names to their values.

See wpstg-restore-config.example.json for a complete example with all filters set to defaults.

Available Filters

Boolean Filters

These filters accept true or false.

Filter Name	Default	Description
`wpstg.backup.restore.keepExistingPlugins`	`false`	When `true`, existing plugins are not deleted before restoring. Backup plugins are merged into the existing directory.
`wpstg.backup.restore.keepExistingThemes`	`false`	When `true`, existing themes are not deleted before restoring.
`wpstg.backup.restore.keepExistingMuPlugins`	`false`	When `true`, existing mu-plugins are not deleted before restoring.
`wpstg.backup.restore.keepExistingMedia`	`false`	When `true`, existing uploads and media files are not deleted before restoring.
`wpstg.backup.restore.keepExistingOtherFiles`	`false`	When `true`, other files in `wp-content` are not deleted before restoring.
`wpstg.backup.restore.innodbStrictModeOff`	`false`	When `true`, disables InnoDB strict mode during database import. This is useful when restoring from a server with different InnoDB settings.

Array Filters

These filters accept an array of strings.

Filter Name	Default	Description
`wpstg.backup.restore.exclude_backup_parts`	`[]`	Parts to skip entirely during restore. Valid values: `plugins`, `themes`, `uploads`, `muplugins`, `wpcontent`, `wpstgdb`, `lang`, `dropins`, `wproot`.
`wpstg.backup.restore.exclude_paths`	`[]`	Directory paths to exclude during file restore. A trailing `/` is added automatically, so `"starter-templates"` matches paths containing `starter-templates/` but not `starter-templates-pro/`. Example: `["starter-templates", "elementor"]`.
`wpstg.backup.restore.exclude.tables`	`[]`	Database table names to skip during database restore. Example: `["wp_comments", "wp_commentmeta"]`.
`wpstg.database.import.excludedQueries`	`[]`	SQL query patterns to skip during database import. Queries containing any of these strings will be excluded.

Important: For exclude_paths, a trailing slash is added automatically. This helps avoid accidental partial matches.

Example Configurations

Restore but keep existing plugins and themes

{
  "version": 1,
  "filters": {
    "wpstg.backup.restore.keepExistingPlugins": true,
    "wpstg.backup.restore.keepExistingThemes": true
  }
}

Restore only the database

Use this configuration to skip all file-related backup parts.

{
  "version": 1,
  "filters": {
    "wpstg.backup.restore.exclude_backup_parts": [
      "plugins",
      "themes",
      "uploads",
      "muplugins",
      "wpcontent",
      "dropins",
      "wproot",
      "lang"
    ]
  }
}

Exclude specific tables from database restore

{
  "version": 1,
  "filters": {
    "wpstg.backup.restore.exclude.tables": [
      "wp_comments",
      "wp_commentmeta",
      "wp_wc_orders"
    ]
  }
}

Exclude specific plugins and themes from file restore

{
  "version": 1,
  "filters": {
    "wpstg.backup.restore.exclude_paths": [
      "starter-templates",
      "elementor",
      "themes/flavor"
    ]
  }
}

Restore files only

Use this configuration to skip the database restore.

{
  "version": 1,
  "filters": {
    "wpstg.backup.restore.exclude_backup_parts": ["wpstgdb"]
  }
}

How Filters Are Consumed

Directly by Restorer: The keepExisting*, exclude_backup_parts, and exclude_paths filters are read directly by the restore tool’s Restorer class to control which parts are restored, whether existing files are deleted first, and which file paths to skip during restore.
Via ApplyFiltersTrait: The database-related filters such as exclude.tables, excludedQueries, and innodbStrictModeOff are consumed by the bundled DatabaseImporter class through the ApplyFiltersTrait. This trait checks FilterConfig as a fallback when WordPress hooks are not available.

Validation and Logging

Unknown filter names are logged as warnings and ignored.
Type mismatches, for example setting a boolean filter to an array, are logged as warnings and skipped.
All active filters are logged at restore startup for debugging.
Malformed JSON produces a warning, and the restore continues with default behavior.
Unsupported config versions produce a warning, and all filters are skipped.

Debugging tip: If a filter does not seem to apply, first check the restore logs for warnings about unknown filter names, invalid types, malformed JSON, or an unsupported config version.

Security

Only whitelisted filter names are accepted.
Only primitive types such as bool and string, plus arrays of strings, are supported.
No callable or code execution is possible through the config file.

WP Staging Restore Tool – Filter Configuration