=== Sitecarry Backup & Migration – Restore, Clone & Cloud Backups ===
Contributors: dotance
Tags: backup, database backup, restore, cloud backup, site migration
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.34.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Back up, restore and migrate your site — files and database in one package — and prove each backup restores before you need it.

== Description ==

Sitecarry builds a single package containing your site's files and a full database
export, then lets you download it from the WordPress admin.

The build runs in short, resumable slices, so it works on shared hosting where a
single PHP request is capped at 30 seconds. If a request times out, the next one
picks up exactly where the last one stopped.

Each package comes with a standalone installer that restores it onto any server —
the same file works for moving a site to new hosting, cloning live to staging, or
rolling a site back.

**What it does**

* Full site package: files plus a complete SQL export
* Your `wp-config.php` is never archived, so the database password and the login
  keys and salts stay on the server; the restore writes that file itself
* Scheduled backups — hourly, twice daily, daily or weekly, with retention
* Optional incremental file backups, with automatic full backups in between
* Upload to Amazon S3, any S3-compatible storage, FTP or Google Drive — Drive
  connects in one click, or with a Google app of your own if you would rather keep
  the plugin's author out of it entirely
* Restore straight from storage when the archives are no longer on the server
* Email or Slack/Discord notification when a backup fails
* Verify that a package is intact, from the admin or WP-CLI
* **Rehearse a backup**, by hand or every week — import it into scratch tables, check
  the row count, prove the result would work as a site, and
  confirm serialized data survives a domain change. Then throw the tables away.
  Nothing on the site is touched
* WP-CLI commands for backing up, listing, verifying and checking status
* Backups run in the background — start one and close the tab
* Resumable build and resumable restore — both survive short PHP execution limits
* Live progress throughout
* **Restore this site with one button** — the package's database is rebuilt in
  tables of its own, swapped in atomically, and the files put back afterwards
* Standalone `installer.php` for moving a site to a different server, where there is
  no WordPress to press a button in
* Serialization-safe URL rewriting, so page builder content survives the move
* Skips caches, `node_modules`, `.git`, and other backup plugins' folders, which is
  usually the difference between a 400MB package and a 40GB one
* Records a manifest describing the origin site (URLs, table prefix, versions)

**Why URL rewriting is the hard part**

WordPress stores a lot of settings as PHP serialized data, where every string
carries its own byte length. Replacing an old domain with a longer one using a
plain search and replace breaks those lengths, and WordPress can then no longer
read the value — which is how a migration quietly wipes widget settings and page
builder layouts. Sitecarry rewrites the serialized form directly and repairs the
lengths, and it also handles the JSON-escaped form (`https:\/\/`) that page
builders such as Elementor store their content in.

**Security**

Packages contain a complete copy of your database. Sitecarry stores them in a
protected folder with an unguessable filename, blocks direct web access via
`.htaccess` and `web.config`, and serves downloads only through an authenticated
admin request — never a public URL.

Every package has its own restore passphrase, shown in the admin and kept out of
the archive. The installer refuses to do anything without it, so an installer
left behind on a server cannot be used by anyone else to overwrite the site. It
also deletes itself and the archive when the restore finishes.

== External services ==

Out of the box Sitecarry talks to nothing but your own server. It contacts an
outside service only when you switch one on, and only with what that service needs
to do its job. It never sends usage data, analytics or licence checks anywhere.

**Amazon S3, or any S3-compatible storage** — used only when you set Storage to S3.
Sitecarry sends your backup archives, and the requests needed to list and delete
them, to the endpoint you enter (by default `https://s3.<region>.amazonaws.com`, or
your own for Backblaze B2, Wasabi, DigitalOcean Spaces, MinIO and so on). What is
sent: the archive itself — which contains your site's files and a full database
export — plus the access key you configured, used to sign each request. Nothing is
sent until you save S3 credentials and run a backup.
For any other S3-compatible provider, the terms are that provider's own.

* Service: Amazon S3, provided by Amazon Web Services (`amazonaws.com`)
* Terms of service: [https://aws.amazon.com/service-terms/](https://aws.amazon.com/service-terms/)
* Privacy policy: [https://aws.amazon.com/privacy/](https://aws.amazon.com/privacy/)

**FTP / FTPS server** — used only when you set Storage to FTP. Sitecarry connects to
the host, port and path you enter and uploads the same archives, authenticating with
the username and password you configured. The server is one you choose, so its terms
are your host's. Plain FTP sends that password and the whole archive unencrypted;
the settings screen recommends FTP over TLS for this reason.

**Google Drive** — used only when you set Storage to Google Drive and complete the
connection. Sitecarry sends you to `https://accounts.google.com` to authorise,
exchanges the code at `https://oauth2.googleapis.com/token`, and uploads, lists and
deletes archives through `https://www.googleapis.com/drive/v3` and
`https://www.googleapis.com/upload/drive/v3`. What is sent: the archives, and an
OAuth token belonging to the Google account you authorise. The connection uses an
OAuth client you create yourself, so the traffic is between your site and Google —
it is not routed through us. Only the `drive.file` scope is requested, which limits
Sitecarry to files it created itself.

* Service: Google Drive API, provided by Google (`googleapis.com`, `accounts.google.com`)
* Terms of service: [https://policies.google.com/terms](https://policies.google.com/terms) and [https://developers.google.com/terms](https://developers.google.com/terms)
* Privacy policy: [https://policies.google.com/privacy](https://policies.google.com/privacy)

**dotance.com — only if you choose "Connect with Google"** — Google Drive needs an
OAuth app, and this is the one Sitecarry lends you so connecting takes a click
instead of ten minutes in the Google console. When you press that button your
browser goes to `https://dotance.com/wp-json/dotance/v1/google/start`, on to
Google's own consent screen, and back; your site then collects the resulting
permission from `.../google/claim`, and asks `.../google/token` for a fresh
access token about once an hour while a backup runs. What is sent: your site's
address, and the permission Google issued for the Drive you approved. What is
never sent: your backups — they upload from your server straight to Google — and
no credentials of any other kind. Choose "Use my own Google app" instead and
nothing touches dotance.com at all.

* Service: Dotance (`dotance.com`), the plugin's author
* Terms of service: [https://dotance.com/terms/](https://dotance.com/terms/)
* Privacy policy: [https://dotance.com/privacy-policy/](https://dotance.com/privacy-policy/)

**Slack, Discord, or any incoming webhook** — used only when you enter a webhook URL
on the Notifications screen. Sitecarry posts a short message to that URL when a
backup finishes or fails: the site name, the outcome, the step it stopped on and the
error text. No archive and no credentials are sent. The destination is the URL you
supply, commonly `https://hooks.slack.com/...`.

* Service: Slack incoming webhooks (`hooks.slack.com`)
* Terms of service: [https://slack.com/terms-of-service](https://slack.com/terms-of-service)
* Privacy policy: [https://slack.com/trust/privacy/privacy-policy](https://slack.com/trust/privacy/privacy-policy)
* Service: Discord webhooks (`discord.com`)
* Terms of service: [https://discord.com/terms](https://discord.com/terms)
* Privacy policy: [https://discord.com/privacy](https://discord.com/privacy)

**Your own site** — Sitecarry sends an HTTP request to your site's own
`admin-ajax.php` to start and continue a background backup. That is a loopback
request to your server, not a third party.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`.
2. Activate it through the **Plugins** screen.
3. Open **Sitecarry** in the admin menu and click **Create Backup**.

== Frequently Asked Questions ==

= Where are packages stored? =

In `wp-content/uploads/sitecarry/`, protected from direct web access.

= What happens if I delete the plugin? =

Sitecarry removes its settings and its scheduled events from the database, and stops
scheduling anything. Your packages in `wp-content/uploads/sitecarry/` are left
exactly where they are, on purpose — deleting a plugin should never be the thing
that destroys your last copy of the site. Delete that folder yourself once you are
sure you no longer need what is in it.

= It says to keep the tab open. Why? =

Background backups need the site to be able to send an HTTP request to itself. Some
hosts block that. When Sitecarry detects it cannot, it falls back to running the
backup from your browser instead, which works everywhere but needs the tab left
open. Ask your host to allow loopback requests if you want unattended backups.

= How do I roll this site back to a package? =

Press **Restore this site** next to the package and confirm. Sitecarry offers to take
a backup of the site as it is first, then rebuilds the package's database in tables of
its own, swaps them in, and puts the files back. Nothing is uploaded by hand and no
passphrase is needed — you are already signed in as an administrator.

What it does not touch: `wp-config.php`, your stored packages, and Sitecarry itself.
The tables it replaced are kept for two days, so a change of mind is quick.

Moving a site to a **different server** is the other case, and it still uses the
downloadable installer — there is no WordPress there yet to press a button in.

= A backup seems stuck. What do I do? =

While a backup is running there is a **Stop backup** button under the progress bar,
and it will tell you if that backup has stopped making progress. Stopping clears
away the half-built package. From the command line, `wp sitecarry stop` does the
same — useful if the admin screen is not loading.

Nothing is lost by stopping: a partial package cannot be restored from anyway.

= Can I run backups from the command line? =

Yes. `wp sitecarry backup` builds one and waits for it, with no execution limit and
nothing to keep open. `wp sitecarry verify --all` checks every package and exits
non-zero if any fails, so it works in a monitoring script. `wp sitecarry status`
prints how the site is protected.

= Does verifying prove the backup will restore? =

No, and nothing short of restoring it does. Verifying proves the archive is the one
that was written, still opens, and holds the files a restore starts from. That
catches truncated uploads, disks that filled mid-write and silent corruption. It
cannot tell you the database inside will import cleanly on a different server.

That last gap is exactly what rehearsing closes — see the next two questions.


= What is the difference between verifying and rehearsing? =

Verifying reads the archive: it confirms the file is the one that was written, that
it still opens, and that the two files a restore cannot start without are inside. It
takes seconds and it cannot tell you the database will import.

Rehearsing imports it. The whole database export is run into tables of the plugin's
own, the row count is compared against what was recorded at backup time, and the
tables are then dropped. Nothing on your site is written to at any point.

That is the difference between "this file is intact" and "this backup works".

= Can it rehearse on its own? =

Yes. Turn on **Rehearse weekly** in Settings and Sitecarry proves the newest full
backup once a week, on Sunday, three hours after your backup hour. You hear from it
only when it fails — the same failures-only rule backups use, for the same reason: a
weekly all-clear stops being read within a month and takes the important one with it.

The hour is not a setting on purpose. It follows the backup hour so the two cannot be
pointed at each other, and a rehearsal stands aside if it finds a backup running.

What gets rehearsed is the newest package that stands on its own. With incremental
backups on, the newest package is usually a difference, so it walks back to the most
recent full one rather than skipping that week.

= Is rehearsing safe to run on a live site? =

Yes, and it is built to be. Every table it creates carries a prefix of its own, every
statement is checked to be acting on one of those tables before it runs, and the
tables are dropped whether the rehearsal passes, fails or is interrupted. Anything a
crash leaves behind is swept away within a day.

It does use processor time and, briefly, database space roughly the size of your
database. It will not start while a backup is running.

= What does rehearsing actually check? =

Six things, in order, and it stops at the first that fails:

1. The archive is the one that was written, and still opens.
2. Every file in it decompresses to the size it claims.
3. The whole database export imports, into tables of the plugin's own.
4. The number of rows matches what was recorded when the backup was taken — which
   catches a dump that imported without error and is simply short.
5. Serialized data survives a domain change.
6. What imported is a WordPress that would work: it knows its own address, it has
   roles, and at least one user holds a role that still exists.

The fifth is the one worth explaining. Widget settings, theme options and every
page-builder layout are stored as serialized data, where each string records its own
byte length. Move to a longer address without repairing those lengths and WordPress
can no longer read the value: the site loads, looks right, and the layouts are gone.
So a rehearsal rewrites the imported rows to a deliberately longer address and checks
WordPress can still read every one of them back.

The sixth catches the other silent one. WordPress stores roles in an option named
after the table prefix, and each user's capabilities under a meta key named after it
too. Restore under a different prefix and rename only the tables, and you get a site
that loads perfectly and locks everybody out. A rehearsal moves the prefix in the
data as a real restore would, then checks a user is still left holding a role that
exists.

To be plain about what step six is: it reads what WordPress reads on its way up. It
does not execute WordPress against the scratch tables. Booting a second WordPress
would mean either a second PHP process — `proc_open` and `exec` are disabled on most
shared hosting — or writing a web-reachable bootstrap into your document root on a
schedule, which is a worse thing to own than the gap it closes.

Nothing is written to your site at any point. The rows are tested in memory, and the
scratch tables are dropped when it finishes.

= Does a passing rehearsal guarantee the restore will work? =

It guarantees more than anything else short of doing it, and less than everything.
It proves the package restores **onto this server** — this PHP, this MySQL. The
server you would actually use in a disaster is a different one, and nothing but a
real restore proves that.

What it does catch is the whole class of failures that make a backup useless without
announcing itself: a truncated dump, a corrupt entry in the middle of the archive, a
database export that is short of rows.
That last gap is what **rehearsing** closes — see below.

= The server is gone. How do I restore? =

Upload `installer.php` into the target folder on the new server, open it, and enter
the package passphrase. If it cannot find the archives it will offer to download
them from your storage — enter a read-only key for that bucket when it asks. Keep a
copy of `installer.php` somewhere other than the site it protects; it is small, and
without it you would have only the archives.

= What do I need to restore an incremental backup? =

Every archive from the last full backup up to the one you are restoring. The
Sitecarry screen tells you how many that is, and the installer refuses to start
while any of them is missing rather than restoring half a site. If that sounds
fragile, leave incremental off — every package is then complete on its own.

= How do I move a site to a different server? =

Download both the Archive and the Installer from the Sitecarry screen, upload them
into the target folder on the other server, create an empty database there, then
open `installer.php` in a browser and enter the package's restore passphrase.

= Does it work on SQLite? =

No, and it tells you rather than pretending. The database export is MySQL, and the
restore installer connects through mysqli, so a package taken on SQLite could not be
restored. On such a site — WordPress Playground, or the SQLite database integration
plugin — the Backups screen says so and the button is disabled.

= What happens when I press "Connect with Google"? =

Google asks whether you allow Sitecarry to keep files in your Drive, and the
permission it issues is handed to your site through dotance.com, which is where
the Google app being borrowed lives. After that your backups upload from your
server straight to Google; dotance.com only turns that permission into a fresh
access token roughly once an hour, because only it holds the app's secret.

If you would rather have nobody in the middle, open "Use my own Google app" on
the Storage screen and create an OAuth client of your own — about ten minutes,
once, and then the plugin talks only to Google.

Sitecarry asks for the narrowest Drive scope that exists: it can see the files it
created itself and nothing else in your Drive.

= Is wp-config.php inside the package? =

No, and deliberately. It holds your database password and the eight authentication
keys and salts that sign every login cookie on the site — secrets that should never
leave the server, least of all inside an archive that gets uploaded to cloud storage.

A restore does not need it. Onto an existing WordPress install the installer keeps
that site's own `wp-config.php` and rewrites the database settings in it; into an
empty folder it writes a fresh one from what you type in, with newly generated keys.
On a multisite, add the multisite constants back by hand after restoring into an
empty folder.

= Can I restore while the site is live? =

Yes, and visitors see a short "being restored" page while it runs — no file is
written into your site root to do that, and scheduled tasks are held back so nothing
writes into tables that are about to be replaced. Keep the tab open; if it closes,
reopening the Backups screen picks the restore up where it stopped.

If a restore stops halfway through putting files back, the database is already the
package's and the files are part old, part new. The screen says so and offers both
ways out: carry on, or restore the safety backup it took at the start.

= Why does moving to another server not run inside WordPress? =

Because it replaces the very files WordPress is running from. Anything doing that
from inside WordPress would be pulling the floor out from under itself partway
through. The installer is a standalone program that never loads WordPress.

= Can it restore into a database that already has a WordPress install? =

Only if it uses the same table prefix, and it will replace those tables. Changing
the table prefix during a restore is not supported yet — use an empty database.

= How large a site can it handle? =

Comfortably into the tens of gigabytes. Sitecarry writes its own archive format
rather than using PHP's zip extension, appending each file to the end and never
rewriting what is already there — so the work grows with the size of the site
instead of with the square of it. ZIP64 is used automatically, so neither the
archive nor any file in it is capped at 4GB.

You still need free disk space for the package, and enough for the database export
while it is being written.

= Can I make backups faster? =

Three things matter, in order.

Compression is the big one, and Sitecarry already avoids most of the cost: images,
video, audio, fonts and archives are stored as they are, whatever level you pick,
because compressing them again is pure waste. If the server is slow and disk is
cheap, set compression to None.

Second, exclude what you do not need. A folder of raw video in uploads will
dominate everything else.

Third, let it run in the background rather than from a browser tab, or use
`wp sitecarry backup`, which has no execution limit at all.

= Where can I see what is inside before installing? =
Screenshots, what is inside, the release history and answers to setup questions are on the [Sitecarry page at dotance.com](https://dotance.com/plugins/sitecarry/).

== Screenshots ==

1. Every package, whether it has been proven to restore, and what has actually happened over the past month — with one line at the top for the only question that matters: is this site protected right now.
2. When backups run, how many are kept, and the weekly rehearsal that proves the newest one still restores.
3. Sending finished packages to Google Drive, Amazon S3, anything that speaks the same protocol, or FTP — each with the set-up it honestly takes, and the error you get when you miss a step.
4. Being told when a backup fails, by email or into Slack or Discord.

== Changelog ==

= 1.34.0 =
* **Restore this site, from the screen.** Press Restore next to a package and it
  goes back: the database is rebuilt in tables of its own and swapped in with one
  atomic rename, then the files are put back through WordPress's own filesystem
  API. It offers to back the site up first, it never touches wp-config.php, your
  packages or Sitecarry itself, and it keeps the tables it replaced for two days.
* Moving a site to a different server still uses the downloadable installer, and a
  package taken on another site is refused here rather than half-restored.
* The importer that a rehearsal and a restore share now lives in one file, so the
  most dangerous code in the plugin has one source.

= 1.33.0 =
* Google Drive connects in one click. Creating a Google app of your own is still
  there, and still the option that keeps everyone else out of it — but if you were
  never going to do that, press Connect with Google and approve it at Google. Your
  backups upload from your server straight to Drive either way; what passes through
  dotance.com is the approval, and a token refresh about once an hour.

= 1.32.0 =
* The activity history can now be cleared, from a link in that card. Useful when a
  site changes hands, or when the failures in it were all yours from testing. The
  packages themselves are untouched — only the record of what has happened.

= 1.31.2 =
* Fixed: on sites large enough that a backup runs in more than one pass, the
  finished archive could be written with an index length that was short by the
  last few entries, and no zip reader would open it — "zip error 21". The length
  now comes from the running total the packer keeps rather than from the
  filesystem, whose answer can lag behind on some hosts. Verify and rehearse
  caught this every time; existing packages that fail to verify should be
  replaced with a fresh backup.

= 1.31.1 =
* Fixed on Windows servers: each backup included every earlier package, and its
  passphrase file, so packages doubled in size with every run. Windows reports the
  uploads folder with backslashes, so the check that skips Sitecarry's own folder
  never matched. Both paths are now normalised the way WordPress does it. Linux and
  macOS servers were not affected.

= 1.31.0 =
* Sitecarry now says so plainly on a site whose database it cannot export into a
  restorable package. The export is MySQL and the installer restores through
  mysqli, so on SQLite — WordPress Playground, or the SQLite integration plugin —
  a backup would build and could never be restored. Backups are refused there
  instead, with the reason on the screen.

= 1.30.0 =
* The restore installer is never written to this server. It is assembled in memory
  and streamed straight to the browser, so the generated file exists only as the
  download itself.

= 1.29.0 =
* **wp-config.php is no longer part of a package.** It holds the database password
  and the eight keys and salts that sign every login cookie, and a package can be
  uploaded to storage outside your control. A restore writes that file instead:
  onto an existing install it updates the one already there, and into an empty
  folder it generates a new one with fresh keys.
* **Restoring starts with a download.** The Restore button used to write a restore
  installer into the WordPress folder; a plugin should not put a program there, so
  it does not any more. Each package row now offers **Get installer**, and the
  screen explains the three steps: download the installer and the archive, upload
  both to the site being restored, open installer.php. The restore itself is
  unchanged, including moving to a new domain, server or table prefix.
* `wp sitecarry stage` is replaced by `wp sitecarry installer <id>`, which prints
  the installer so you can redirect it to a file.
* Loopback requests now pass their SSL verification through core's own
  `https_local_ssl_verify` filter rather than switching it off outright.
* The readme name matches the plugin header.

= 1.28.0 =
* Requires WordPress 6.2 or later. Every database query that names a table now passes
  the name through `$wpdb->prepare()` as an identifier placeholder.
* Inside WordPress, all remote requests go through the WordPress HTTP API. The
  standalone restore installer, which runs without WordPress, keeps its own transport.
* The plugin no longer raises PHP's execution time limit. Each step is sized to fit
  inside the host's limit and resumes in the next request.
* Settings are sanitized field by field as they are read from the form.
* The restore installer downloads from a file on disk instead of being echoed.
* Plugin constants now use the `SITECARRY_` prefix.
* The package manifest no longer records the content folder path, which nothing read.

Older entries: [dotance.com/plugins/sitecarry/](https://dotance.com/plugins/sitecarry/)

== Upgrade Notice ==

= 1.34.0 =
Adds one-button restore: put this site back to any package from the Backups screen,
with a safety backup taken first. wp-config.php, your packages and Sitecarry itself
are never touched.

= 1.15.0 =
Housekeeping and a proper uninstall. Deleting the plugin now clears its settings and
schedules; your backup packages are left where they are.

= 1.14.0 =
Fixes ten bugs, most of them cases where an interrupted backup could resume into a
corrupt archive. Worth taking.
