Content Interchange

Move site state, not a database dump

Content Interchange is TAW's native way to move a site's state between environments — a snapshot you can read, diff, review, and roll back, instead of a .wpress black box or a 400 MB .sql.

It works because a disciplined TAW site keeps everything in _taw_ fields and options instead of a plugin stack: no page builders, no ACF, menus in code, forms as runtime taw_submission entries. What a generic migration tool has to haul — dozens of plugin tables, serialized builder blobs, orphaned option rows — simply isn't there. So the site's real state fits in a single JSON file that a person (or a code agent) can open and understand.

php bin/taw content:export --migrate --output=/tmp/site.json   # whole-site state
php bin/taw content:import /tmp/site.json                       # dry-run: what would change
php bin/taw content:import /tmp/site.json --yes                 # apply (rollback snapshot first)

When to use what

The dividing line: a full-site tool clones an entire WordPress install, database and uploads and all, and is the right call when there's no site there yet or you're recovering one. Content Interchange moves the reviewable delta between two installs that already exist and already run the TAW stack.

What's in a snapshot

TAW\Core\Content\Exporter::snapshot($scope) produces a plain array, json_encode-ready. schema is "1.1"; the importer also accepts "1.0". Full JSON Schema: resources/schema/content-interchange-1.1.json in the taw/core package.

Never carried: revisions, transients, non-allowlisted core / plugin options, nav_menu / nav_menu_item (code-owned in TAW themes), non-_taw_ post meta. Drafts are excluded unless --include-drafts.

Scope flags

Filters

Each of these belongs in the theme's inc/customizations.php.

// Add a non-content CPT to the export (rarely needed — a CPT with a Metabox
// attached is auto-included as of taw/core v1.26.0).
add_filter('taw_content_export_post_types', fn (array $types) => [...$types, 'event']);

// Extend the always-on core option allowlist.
add_filter('taw_content_export_core_options', fn (array $keys) => [...$keys, 'my_theme_accent']);

// Extend the --with-settings environment allowlist.
add_filter('taw_content_export_settings_options', fn (array $keys) => [...$keys, 'rss_use_excerpt']);

The --with-settings allowlist

A second, opt-in allowlist — separate from the always-on core one — for environment-ish settings a full migration wants but a routine content sync must never touch: permalink_structure, timezone_string, gmt_offset, date_format, time_format, start_of_week, sticky_posts (exported as slugs), blog_public, default_comment_status, default_ping_status, WPLANG.

These are import-gated as well — content:import skips them unless you also pass --with-settings (or tick the box on the admin screen).

Import — dry-run mandatory, rollback automatic

TAW\Core\Content\Importer consumes a snapshot or a change-set ({ taw_changeset, operations: [...] }, which content:diff emits). Records match by natural key, never by numeric ID:

• posts by (type, slug), or (type, match_key) for a slug-less draft
• options by key · terms by (taxonomy, slug)
• users by login, then email · comments by a content hash

Apply order

Dependency-first and deterministic:

users → terms → media (sideload + build old→new ID map) → posts → comments → settings

What happens on apply

1. Rollback first. A full, maximal-scope Exporter snapshot (users, settings, all media, drafts) is written to wp-content/uploads/taw-private/ — an .htaccess-denied directory — and its path is named in the report. Restore with content:import <that-file>.json --yes.
2. Media is matched to an existing attachment by filename, or sideloaded from url with its title / description / alt / caption. The old → new ID map is applied to wp-image-N, "id":N and "ids":[…] in post_content and to image / files field values before anything is written.
3. Portable transforms are reversed. page_on_front / page_for_posts / sticky_posts (slugs), post.parent (slug), featured_media (filename) and author ({login,email}) all resolve back to a local ID before the diff and the write.
4. Posts via wp_insert_post / wp_update_post; field meta via Metabox::writeMeta() — the same sanitize + wp_slash path an admin metabox save uses. Author resolves login → email → the importing user (with a warning).
5. Users via wp_insert_user / wp_update_user. Roles are sanitised against the roles the target site actually defines — a role the target doesn't have is never granted. New accounts get a random password unless a portable hash was exported.
6. Comments are recreated, remapped to their post by slug, threading rebuilt from parent_ref, counts recomputed.
7. Settings options — only if --with-settings.

A clean --migrate export → import --yes against the same site reports 0 created / 0 updated / 0 deleted. plan() reports zero changes and apply() skips every record the dry-run shows unchanged, so re-running an import never churns post_modified dates.

Conflict policy

Per-record update (overwrite) / create (only new) / skip — global default via --policy= or the admin selector.

Workflow recipes

php bin/taw content:export --migrate --output=prod.json

php bin/taw content:import prod.json            # review the diff
php bin/taw content:import prod.json --yes --with-settings

# on staging
php bin/taw content:export --posts=pricing,features --output=promo.json
# on production
php bin/taw content:import promo.json --yes

php bin/taw content:export --output=before.json
cp before.json after.json          # agent rewrites fields in after.json
php bin/taw content:diff before.json after.json --out=changes.json
php bin/taw content:import changes.json           # review
php bin/taw content:import changes.json --yes     # apply just the change-set

php bin/taw content:export --migrate --with-comments --output=site.json
# stand up the new install with the theme deployed via git, then:
php bin/taw content:import site.json --yes --with-settings

The admin screen — Tools → TAW Data

For non-CLI use, Tools → TAW Data (capability export; import needs taw_import_content, granted to anyone with manage_options).

• Export — a button plus checkboxes mirroring the CLI flags: referenced media, unreferenced media, drafts, users, environment settings. Password hashes and comments sit behind an Advanced disclosure with a warning. Streams taw-content-<host>-<timestamp>.json.
• Import — upload a snapshot or change-set → a mandatory review table (per record, per field: unchanged / changed / new / would-delete) with a conflict-policy selector and an "also apply environment settings" checkbox → an explicit "Apply N changes" button. There is no one-click apply.
• Every apply writes the rollback snapshot to uploads/taw-private/ first and links it in the result notice.

REST export

GET /wp-json/taw/v1/content/export — the same snapshot the Export button produces, for CI or a headless build step. Capability export. Parameters: types, since, include_media, include_drafts.