File Sync Workflow

Two paths for transferring files

Page Assets (new in v1.10) is the preferred path for most work. It walks the on-disk asset directory directly, so it picks up files placed there by modules outside the standard field flow (notably MediaHub, but also any custom uploader). File Sync is the original field-aware path, kept for simpler cases where you only care about standard File and Image field uploads.

Page Assets (preferred)

pw_page_assets reads and writes site/assets/files/{pageId}/ directly. It supports inventory, download, upload, delete, and compare actions. Both directions work (local to remote and remote to local), and the call accepts site: "local" | "remote" | "both" for the read verbs. PW image variations (name.WIDTHxHEIGHT.ext) are skipped by default because they are regenerated on demand and would produce noisy diffs.

Typical usage

Sync all assets for the About page to production.

Or compare what differs across sites:

Compare the assets for the About page between local and production.

Page id drift

Pages are matched by canonical PW path. Each side resolves its own pageId from that path before walking its own site/assets/files/{pageId}/ directory, so a local 1234 and a remote 5678 can both resolve to /about/ without anything getting confused. Every result reports localPageId, remotePageId, and an idDrift boolean so you can see at a glance which physical disk directory was read or written on each environment.

Drift since last pull

page.meta.json embeds a pageAssets snapshot at pull time (relative path, size, md5, plus a directory hash, asset count, and total bytes). Subsequent pw_page_assets calls include a driftSinceLastPull block that compares the snapshot baseline against the live inventory on the side it represents, so you can answer "what has changed in production since I last pulled?" without a fresh remote round-trip.

Parameters

File Sync (legacy)

File sync compares file and image fields between your local ProcessWire install and a remote site, then uploads, downloads, or deletes files to bring them into alignment. It iterates each page's fieldgroup, so it only sees files attached as FieldtypeFile or FieldtypeImage. Use Page Assets (above) if a module like MediaHub is storing files outside the standard field flow.

How it works

File sync requires both PW_PATH (local) and PW_REMOTE_URL (remote) to be configured. It reads files from the local site/assets/files/{pageId}/ directory and talks to the remote API for inventory and transfer.

The process for each page:

1. The remote API returns an inventory of every file on each file/image field: filename, size, MD5 hash, description, and image dimensions.
2. PromptWire compares this against the local files on disk.
3. Files that exist locally but not remotely are uploaded (base64-encoded via the API).
4. Optionally, files that exist remotely but not locally can be deleted with deleteRemoteOrphans: true.

Usage

Sync files for the About page to production.

Or use pw_file_sync with localPath pointing to the page's sync directory. Like other write operations, file sync is dry-run by default.

Parameters

Timeouts

File sync operations use a longer timeout (120 seconds vs the standard 60) because base64-encoded uploads can be large. If you're syncing many high-resolution images, consider doing it in batches.