Stable 1.0.1 WordPress 6.5+ PHP 7.4+

BackupFlow documentation

A complete operator and developer guide for creating WordPress backups, restoring a site, migrating between domains, connecting remote storage, and resolving common BackupFlow issues.

25 minute read Operator + developer reference Last reviewed for version 1.0.1

Set up your first backup Install the plugin, run preflight checks, choose a destination, and create a recoverable archive. Restore or migrate a site Import a compatible BackupFlow ZIP and restore files, database content, or the complete site. Connect remote storage Configure Website Server, FTP, or Google Drive as a backup destination. Resolve a problem Use preflight output and live job logs to identify the failing backup or restore stage.

What BackupFlow does#

BackupFlow is a WordPress administration plugin for manual full-site, files-only, and database-only backups. It also provides compatible ZIP restore and migration workflows with destination URL protection and serialized-aware URL replacement.

Three backup modes

Create a full backup, back up site files only, or export the WordPress database only.

Resumable processing

Long backup, upload, and restore operations are divided into smaller jobs instead of one blocking request.

Local and off-site storage

Store archives on the website server or upload additional copies through FTP or Google Drive.

Restore safeguards

Protect wp-config.php, create a safety database backup, and keep destination URLs active during migration.

Available in BackupFlow 1.0.1

This version supports manual backups, restore and migration, Website Server storage, FTP, and Google Drive. Features marked as Coming Soon are not available yet.

System requirements#

BackupFlow checks the hosting environment before starting a backup, import, or restore. Blocking checks must pass before the job can proceed.

Requirement	Type	Purpose	Resolution
WordPress 6.5 or later	Required	Provides the supported WordPress administration and database environment.	Update WordPress before installing BackupFlow.
PHP 7.4 or later	Required	Runs the plugin and its backup, restore, encryption, and storage logic.	Change the PHP version from the hosting control panel.
Single-site WordPress	Blocking	BackupFlow currently supports single-site WordPress installations only.	Use BackupFlow on a single-site installation.
64-bit PHP	Blocking	Required for reliable handling of large file sizes and ZIP archives.	Move the site to a 64-bit PHP environment.
PHP ZipArchive	Blocking	Creates and extracts BackupFlow ZIP archives.	Enable the PHP `zip` extension.
Writable BackupFlow folders	Blocking	Stores archives, temporary files, jobs, logs, and imports.	Correct ownership and permissions under `wp-content`.
Sufficient free disk space	Blocking	Backup creation and restore can require both archive and temporary working space.	Free server space or use a larger storage volume.
Database read/write access	Blocking	Required for export, import, prefix handling, and URL replacement.	Verify database credentials and privileges.
FTP extension	FTP only	Required for FTP connection and resumable archive upload.	Enable the PHP FTP extension.
Outbound HTTP access	Drive only	Required to exchange OAuth tokens and upload to Google Drive APIs.	Allow outbound HTTPS requests to Google services.

Large-site planning

Chunked processing improves reliability, but large sites still need enough disk capacity, PHP memory, database availability, execution stability, and remote-storage connectivity.

Installation#

BackupFlow can be installed from the WordPress plugin directory, uploaded as a plugin ZIP, or transferred through FTP. Administrator access is required.

Sign in to WordPress as an administrator.
Open Plugins → Add New Plugin.
Search for BackupFlow.
Select Install Now, then Activate.
Open BackupFlow in the WordPress admin menu.

Download the BackupFlow plugin ZIP.
Open Plugins → Add New Plugin → Upload Plugin.
Select the ZIP file and choose Install Now.
Activate BackupFlow when installation completes.
Open the first-run wizard.

Extract the plugin ZIP on your computer.
Upload the backupflow folder to /wp-content/plugins/.
Open the WordPress Plugins screen.
Activate BackupFlow.
Open BackupFlow and run the first preflight check.

What happens during activation#

Activation creates default settings, initializes the backup catalogue, prepares protected BackupFlow directories, and redirects eligible administrators to the setup experience.

Created storage structure

wp-content/backupflow/
├── backups/
├── jobs/
├── logs/
└── tmp/
    └── imports/

Quick start#

For a first recovery point, create a full local backup, download a copy, and then configure FTP or Google Drive for off-site storage.

Open Create Backup

From WordPress admin, open BackupFlow → Create Backup.

Select files and database

Choose both components to create a complete site archive. Use a single component only when you intentionally need a files-only or database-only recovery point.

Select Website Server

Use the local destination for the first backup. FTP and Google Drive are available after their credentials are configured.

Review preflight results

Resolve every blocking item before starting the job. Warnings should also be reviewed because they can affect reliability.

Start the backup

Keep the browser tab open while the live modal advances the resumable job and shows database, file, ZIP, and storage progress.

Verify and download

Confirm the archive appears in BackupFlow → Backups, then download a copy or verify the remote upload.

Test restores before relying on a backup strategy

A backup is not operationally proven until it has been restored successfully on a staging or disposable environment.

Dashboard#

The BackupFlow dashboard provides a high-level view of site protection, the latest backup, local storage status, server runtime information, and recent backup records.

Dashboard information#

Protection status: Indicates whether recent backup records exist.
Latest backup: Shows the latest archive date, type, size, and storage context.
Local storage: Summarizes BackupFlow storage availability and usage.
Runtime details: Surfaces PHP, WordPress, and server information relevant to backup operations.
Recent backups: Provides direct access to restore, download, and delete actions.

Create a backup#

The Create Backup wizard guides administrators through backup contents, destination selection, readiness checks, and job execution.

Backup types#

Full backup

Includes WordPress files and selected WordPress database tables. This is the standard choice for full recovery and migration.

Files-only backup

Includes site files such as plugins, themes, uploads, and WordPress content files without exporting database tables.

Database-only backup

Exports the WordPress database without packaging site files. Useful before content, configuration, or database-level changes.

Archive naming

Files use a site host, timestamp, and type pattern such as backupflow-example.com-YYYYMMDD-HHMMSS-full.zip.

Choose a destination#

Website Server is available immediately. FTP and Google Drive remain unavailable until their connection settings are saved successfully.

Live backup progress#

The live job modal displays the current operation, percentage progress, recent logs, completion state, cancellation controls, and a download link when a local archive is available.

Keep the browser tab open

BackupFlow uses repeated authenticated requests to advance resumable jobs. Closing the tab can pause progress until the job is resumed.

Backup library#

The backup library stores catalogue records for local backups, imported archives, and remote-uploaded backup jobs. Available actions depend on whether the local ZIP remains present.

Action	When available	Behaviour
Restore	A compatible local BackupFlow ZIP is available.	Starts the restore workflow for files, database, or both.
Download	The local ZIP exists inside the protected BackupFlow backup directory.	Streams the archive through a nonce-protected admin endpoint with HTTP Range support.
Delete	The record is removable by an administrator.	Deletes the local archive when present and removes its catalogue record.
Search and pagination	Available on the backup listing screen.	Filters and navigates stored backup records in the WordPress admin interface.

Remote upload does not replace local catalogue logic

A remote destination is an additional copy. Confirm that the remote upload completed and that the local archive remains available when a direct in-dashboard restore is required.

Restore and migrate#

BackupFlow can restore a compatible archive created by BackupFlow. Imported ZIP files must include a valid backupflow-manifest.json.

Upload and restore a ZIP#

Open Restore & Migrate

Navigate to BackupFlow → Restore & Migrate.

Select the BackupFlow ZIP

Drop or choose an archive created by BackupFlow. Generic ZIP files are not accepted.

Choose the operation

Select database-only, files-only, full restore, or upload-only to add the archive as a restore point.

Complete the chunked upload

Large archives are uploaded in chunks with progress, transfer logs, retry handling, and cancellation support.

Confirm the restore warning

Review the impact because current files, database content, or both may be replaced.

Verify the restored site

Test login, pages, media, forms, permalinks, checkout, emails, scheduled tasks, and cache configuration.

Restore modes#

Mode	Restores	Typical use
Full restore	Files and database	Complete rollback, recovery, cloning, or domain migration.
Files only	Archive entries under `files/`	Recover plugins, themes, uploads, or other site files without replacing database data.
Database only	Database SQL parts	Recover content, settings, users, or plugin data while preserving current files.
Upload only	No immediate restore	Add a compatible ZIP to restore points for later use.

Production restores can destroy newer data

On WooCommerce, membership, booking, LMS, or lead-generation sites, restoring an older database can remove orders, users, submissions, and changes created after the backup.

Storage destinations#

BackupFlow supports Website Server storage, FTP, and Google Drive. Remote destinations require connection details and may depend on hosting extensions or outbound network access.

Website Server#

Completed local ZIP archives are stored under wp-content/backupflow/backups. BackupFlow places protective index.php and .htaccess files in its storage folders.

Default archive location

wp-content/backupflow/backups/

FTP storage#

FTP requires PHP FTP support and valid server credentials. BackupFlow uploads to a temporary .part path and renames the file after the transfer completes.

Setting	Description
Host	FTP server hostname or IP address.
Port	FTP service port, commonly 21 unless the server uses a custom value.
Username	FTP account permitted to write to the remote destination.
Password	FTP account password. BackupFlow encrypts saved secrets when supported.
Remote folder	Destination directory where completed ZIP files should be stored.
Passive mode	Connection mode that is commonly required behind firewalls or NAT.

Google Drive#

Google Drive storage uses an administrator-provided OAuth client. The plugin stores the Client ID, Client Secret, refresh token, and an optional destination folder ID.

Create or select a Google Cloud project.
Enable the Google Drive API.
Create OAuth client credentials for a web application.
Add the BackupFlow callback URL shown on the Storage settings screen.
Save the Client ID and Client Secret in BackupFlow.
Select Connect Google Drive and complete consent.
Optionally enter a Drive folder ID for archive uploads.

Google Drive scope

BackupFlow uses the https://www.googleapis.com/auth/drive.file scope and resumable uploads with approximately 8 MB chunks.

Settings and retention#

The Settings screen controls backup retention, file exclusions, restore safeguards, FTP details, and Google Drive connection data.

Backup retention#

The default retention count is 8. When retention cleanup runs, older catalogue records and associated local files can be removed after newer backups exceed the configured limit.

Default excluded paths#

Default exclusions

wp-content/cache
wp-content/upgrade
wp-content/backupflow
wp-content/uploads/backupflow
node_modules
.git

Restore safeguards#

Do not overwrite wp-config.php: Enabled by default to preserve destination database credentials, salts, and environment-specific configuration.
Create a safety database backup: Enabled by default before a database restore to create a local database-only safety ZIP.

Interface screenshots#

Use these screenshots to identify the main BackupFlow screens, settings, and workflow controls. Select any image to enlarge it.

BackupFlow dashboard showing protection status and recent backups — **Dashboard overview**
Protection status, latest backup information, storage status, runtime details, and recent backups.

BackupFlow Create Backup wizard choosing files and database — **Create Backup wizard**
Select files, database, or both before choosing the storage destination.

BackupFlow backup library with restore download and delete actions — **Backup library**
Review stored backups and access restore, download, and delete actions.

BackupFlow Restore and Migrate screen — **Restore & Migrate**
Upload a compatible BackupFlow archive and choose a restore or upload-only operation.

BackupFlow secure upload progress modal — **Secure upload progress**
Chunk progress, transfer logs, retry handling, and cancellation for large ZIP imports.

BackupFlow backup destination step — **Backup destination**
Select Website Server, FTP, or Google Drive after remote connections are configured.

BackupFlow backup progress modal with logs — **Backup progress**
Live scan, database export, ZIP packaging, remote upload, and completion logs.

BackupFlow upcoming features screen — **Upcoming features**
Preview features planned for future releases, including scheduled backups, cloning, additional cloud storage, WP-CLI, and support tools.

BackupFlow storage settings for FTP and Google Drive — **Storage settings**
Configure FTP access and Google Drive OAuth credentials with an optional folder ID.

Backup engine#

BackupFlow stores resumable job state and advances each operation through authenticated requests. A backup moves through preparation, database export, file scanning, ZIP creation, manifest finalization, remote upload, and cleanup.

Run preflight

Confirm WordPress mode, PHP architecture, ZipArchive, storage permissions, disk space, database access, and destination requirements.

Prepare workspace

Create a temporary job workspace under wp-content/backupflow/tmp and store intended paths, identifiers, and manifest values.

Export the database

Export selected WordPress-prefixed tables into resumable SQL files such as database/database-000001.sql.

Scan site files

Scan from ABSPATH, skip symbolic links, and apply configured exclusion rules.

Write the ZIP archive

Add selected files under the archive files/ prefix and include exported database parts when applicable.

Write the manifest

Add backupflow-manifest.json containing format, version, URLs, table prefix, inclusions, counts, sizes, and hashes.

Upload and complete

Finish locally or upload through FTP or Google Drive, update the catalogue, apply retention, and remove temporary job data.

Restore engine#

The restore engine validates the archive, obtains a restore lock, optionally creates a safety backup, restores files, imports database parts, protects the destination URL, rewrites source URLs, verifies the result, and cleans temporary data.

Acquire restore lock

Only one active restore should run. Abandoned restore jobs can be cleaned or cancelled before a new restore begins.

Create a safety database backup

When enabled, BackupFlow creates a database-only local ZIP before importing database content.

Restore files

Extract archive entries under files/ into ABSPATH in chunks. By default, wp-config.php is skipped.

Import database parts

Extract SQL parts, import statements in chunks, and rewrite source table prefixes to the destination prefix when necessary.

Protect destination URL

Force home and siteurl back to the current destination values so WordPress does not redirect to the source domain mid-restore.

Rewrite URLs

Replace source home, site, and content URLs with current destination URLs using serialized-aware handling where supported.

Verify and clean up

Flush rewrite rules, clear temporary extraction files, release the restore lock, and mark the job complete.

Migration behaviour#

When a backup is restored to another domain or WordPress installation, BackupFlow uses the archive manifest and current environment to reconcile URLs and database table prefixes.

URL replacement#

BackupFlow can replace source home, site, and content URLs with destination values. The replacement process accounts for serialized WordPress data where supported.

Database table prefix handling#

Source table prefixes may be rewritten to match the destination WordPress table prefix during database import.

Foreign key fallback#

Version 1.0.1 improves imports for plugin tables where foreign key constraints are rejected by the destination database.

Environment-specific configuration still requires review

After migration, verify caching, object cache, cron, SMTP, payment webhooks, CDN, security rules, licence keys, API callbacks, and host-specific settings.

Security and privacy#

A BackupFlow archive can contain personal data, customer records, WordPress users, uploaded files, plugin configuration, and secrets stored by other plugins. Treat every archive as production data.

Administrator permissions

BackupFlow administration screens and operations require manage_options.

Nonce verification

Authenticated AJAX operations verify the backupflow_admin nonce.

Path validation

Delete, import, download, and cleanup operations check that paths remain inside expected BackupFlow storage roots.

Encrypted stored secrets

FTP passwords, Google client secrets, and refresh tokens are encrypted with OpenSSL and AUTH_KEY when available.

Protected directories

BackupFlow writes index.php and .htaccess guards into its storage directories.

Archive preservation on uninstall

Uninstall removes plugin options and job records but intentionally leaves backup archive files in place.

Do not expose the BackupFlow storage directory publicly

Server-level rules should prevent direct archive access. Review Nginx or custom web-server configuration because .htaccess protection applies only where supported.

Best practices#

Create a full backup before WordPress core, WooCommerce, plugin, theme, payment, checkout, page-builder, or custom-code changes.
Maintain at least one off-site copy through FTP, Google Drive, or a manual download.
Use database-only backups before content, settings, WooCommerce, membership, LMS, or database-level changes.
Use files-only backups before replacing themes, plugins, uploads, templates, or custom code.
Test complete restores in staging at a regular interval.
Avoid production database restores during active orders, registrations, bookings, submissions, or editorial work.
Keep wp-config.php protection enabled unless replacing it is intentional and reviewed.
Monitor disk capacity before creating or restoring large archives.
After migration, verify login, permalinks, media, forms, checkout, email, cron, webhooks, and cache behaviour.
Document where local and remote copies are stored and who has access to them.

Recommended operational rule

A site is not considered recoverable until the archive location is known, access is confirmed, and a restore has been tested successfully.

Troubleshooting#

Start with the preflight result, then review the most recent live job log message. The failing stage normally identifies whether the problem is storage, database, ZIP, upload, extraction, or URL replacement.

Backup does not start

Enable PHP ZipArchive.
Confirm wp-content/backupflow/backups is writable.
Free enough disk capacity for the archive and temporary work files.
Verify the site is not a multisite migration target.
Confirm database access and server stability.

Backup pauses or appears stuck

Keep the WordPress admin tab open.
Check browser developer tools for failed AJAX requests.
Review security, firewall, CDN, or hosting rules that may block repeated admin requests.
Resume the job from BackupFlow if the interface provides a resumable state.
Reduce competing server load before retrying.

ZIP import fails

Use a .zip created by BackupFlow.
Confirm the archive contains backupflow-manifest.json.
Check write access under wp-content/backupflow/tmp/imports.
Retry after checking upload limits, reverse proxy limits, and security software.
Do not rename or modify the internal archive structure.

Restore redirects to the old domain

Use BackupFlow 1.0.1 or later.
Verify the destination WordPress Address and Site Address before restore.
Allow URL replacement to complete before closing the restore modal.
Clear browser, plugin, CDN, host, and object cache.
Search the destination database for hard-coded source URLs if a plugin stores non-standard data.

FTP is unavailable or upload fails

Enable the PHP FTP extension.
Verify host, port, username, password, and remote folder.
Try passive mode.
Confirm the FTP user can create and rename files in the destination directory.
Check firewall and hosting outbound connection restrictions.

Google Drive connection fails

Verify the Google Drive API is enabled.
Check the OAuth Client ID, Client Secret, and authorised redirect URI.
Reconnect with a consent prompt if Google does not return a refresh token.
Confirm the hosting server can make outbound HTTPS requests to Google APIs.
Validate the optional folder ID and account access.

Restore completes but the site has errors

Clear all caches and regenerate permalinks.
Check PHP error logs and WordPress debug logs.
Verify plugin and theme compatibility with the destination PHP version.
Confirm file ownership and permissions after extraction.
Review environment-specific settings such as Redis, SMTP, CDN, and webhooks.

Developer reference#

BackupFlow is organised into PHP services, WordPress admin JavaScript, CSS, image assets, and translation files. The table below maps the main plugin files to their responsibilities.

File	Responsibility
`backupflow.php`	Plugin header, constants, includes, lifecycle hooks, and bootstrap.
`includes/helpers.php`	Defaults, storage paths, secure directories, catalogue helpers, AJAX verification, JSON helpers, encryption, manifest reads, and upload sizing.
`includes/class-backupflow.php`	Main container for jobs, database, filesystem, storage, backup, restore, migration, preflight, and administration services.
`includes/class-backupflow-admin.php`	Admin menu, screens, settings, OAuth callback handling, AJAX endpoints, downloads, notices, tables, wizard, and modal markup.
`includes/class-backupflow-backup-manager.php`	Prepare, database export, file scan, ZIP creation, finalization, remote upload, retention, and cleanup.
`includes/class-backupflow-restore-manager.php`	Restore lock, safety backup, file restore, SQL extraction/import, URL rewrite, destination protection, and verification.
`includes/class-backupflow-database.php`	Table export, SQL parts, import sessions, foreign-key fallback, prefix rewrite, and serialized-aware URL replacement.
`includes/class-backupflow-file-system.php`	File scanning, exclusions, ZIP packaging, archive entry listing, extraction, and manifest additions.
`includes/class-backupflow-job-store.php`	Job creation, JSON persistence, summaries, logs, completion, failure, cancellation, and cleanup.
`includes/class-backupflow-preflight.php`	Readiness checks for backup, import, restore, FTP, and Google Drive.
`includes/class-backupflow-migrator.php`	Moves imported BackupFlow ZIP files into storage and creates restore-point records.
`includes/class-backupflow-storage*.php`	Storage registry and local, FTP, and Google Drive adapters.
`assets/js/admin.js`	Wizard interaction, preflight, modal progress, polling, uploads, retries, cancellation, search, and pagination.
`assets/css/admin.css`	WordPress admin styling for screens, tables, settings, restore import, roadmap, sidebar, and modal.
`languages/*`	Translation templates and compiled/source translation files.
`uninstall.php`	Removes BackupFlow options and job records while preserving archive files.

Internal storage paths#

Storage paths

wp-content/backupflow/
wp-content/backupflow/backups
wp-content/backupflow/tmp
wp-content/backupflow/tmp/imports
wp-content/backupflow/logs
wp-content/backupflow/jobs

WordPress options#

Option and transient keys

backupflow_settings
backupflow_jobs
backupflow_backups
backupflow_activation_redirect

AJAX and admin actions#

Action	Purpose
`backupflow_preflight`	Run backup, import, or restore readiness checks.
`backupflow_start_backup`	Create a new backup job.
`backupflow_process_job`	Advance backup or restore work through the next resumable chunk.
`backupflow_get_job`	Return the current job state and logs.
`backupflow_resume_job`	Resume a running or paused job.
`backupflow_start_restore`	Create a restore job from a backup record.
`backupflow_start_import`	Create a chunked upload session for a ZIP import.
`backupflow_upload_chunk`	Append an uploaded chunk to the import target.
`backupflow_complete_import`	Validate the uploaded archive and create an imported backup record.
`backupflow_cancel_import`	Remove incomplete import state and temporary files.
`backupflow_cancel_job`	Cancel a running job and release the restore lock when applicable.
`backupflow_delete_backup`	Delete a local archive and remove its catalogue record.
`admin_post_backupflow_download_backup`	Download a ZIP with nonce verification and HTTP Range support.
`admin_post_backupflow_save_settings`	Save general, FTP, or Google Drive settings.

Release notes#

Version 1.0.1#

Improved restore imports for plugin tables with rejected foreign key constraints.
Improved migration safety for database table prefix handling during restore.
Protected the destination site URL during database restore.
Removed the manual translation loader so WordPress.org can load translations automatically.
Refreshed translation catalogues for restore messages.

Included language files#

Locale	Language
`en_US`	English — United States
`en_GB`	English — United Kingdom
`fr_FR`	French
`de_DE`	German
`es_ES`	Spanish
`pt_BR`	Portuguese — Brazil

Frequently asked questions#

Is BackupFlow free?

Yes. BackupFlow includes manual backup, restore, migration, Website Server storage, FTP, and Google Drive functionality.

Can BackupFlow restore any ZIP file?

No. The ZIP must be a compatible BackupFlow archive containing a valid backupflow-manifest.json.

Does BackupFlow support multisite migration?

No. BackupFlow 1.0.1 supports single-site WordPress installations only.

Does uninstall delete backup files?

No. Uninstall removes BackupFlow settings, job data, catalogue data, and the activation redirect transient while preserving archive files.

Can BackupFlow migrate to another domain?

Yes. A compatible archive can be restored to another WordPress installation, with source URLs replaced by destination URLs and table prefixes reconciled when required.

Does Google Drive require my own OAuth application?

Yes. Configure a Google Client ID and Client Secret, complete the connection flow, and allow BackupFlow to store the returned refresh token.

Why should I keep an off-site copy?

A server failure, account suspension, malware incident, or storage corruption can make local archives unavailable. An FTP, Google Drive, or downloaded copy reduces that single point of failure.