Skip to content
Docs
WebsiteDownload
Plugins

Sync for plugins

Tell Sync which of your plugin's tables are content, which are what visitors leave behind, and which never leave a site.

2 min readView as Markdown
On this page

Sync moves tables by name, without the prefix, and groups them the way people choose. A plugin's tables named after it, like bookings_* for acme/bookings, are one group under the plugin's label, pulled by default and not pushed. To say more, add sync to the plugin's composer.json. No code, and nothing to depend on.

JSON
"extra": { "cms": { "sync": {
  "keep": ["bookings_tokens", "bookings_queue"],
  "groups": {
    "bookings": {
      "label": "Bookings",
      "description": "Appointments and the people who made them.",
      "tables": ["bookings_*"],
      "push": false,
      "pull": true
    }
  }
} } }
KeyMeaning
keepTables that never leave a site: tokens, queues, keys, anything that only makes sense where it was made. A name, or a prefix ending in *.
groups.<id>.tablesThe tables that make up a group. A table belongs to the first group that names it.
groups.<id>.push, pullWhether the group is ticked by default when pushing and when pulling. Push what a team makes; leave what visitors leave behind unticked.

#What your plugin can count on

  • A table is replaced as a whole, or for entries and revisions by collection. Rows arrive with your schema on the receiving side: columns it doesn't have are refused before anything moves, columns it has and the rows don't get their defaults.
  • Addresses and folder paths in every text column are rewritten, inside JSON and PHP-serialized values too. Keep absolute URLs out of your data where you can; when you can't, they still come out right.
  • Files your plugin keeps under content/ move with Site Files, and settings in config/ with Settings. storage/ never moves: keep there what belongs to one site.
  • After a switch, the cms.sync hook runs, as after php cms sync, the cache is flushed and the site queues a full build. Rebuild any index of your own there.

#The protocol

Two sites talk over POST /api/sync/v1/<op> with a gzipped body. Each request carries X-Sync-Time, X-Sync-Nonce and X-Sync-Signature, an HMAC-SHA256 with the key's secret over cms-sync-1, the operation, the time, the nonce and the SHA-256 of the body, joined by newlines. Requests older than five minutes or seen before are refused. Reads need pulls allowed on that site, writes need pushes allowed, and a public site answers only hello without a licence.