Download the PHP package nyoncode/laravel-backup-manager without Composer

Backup Manager for Laravel

A powerful, extensible and CLI-first backup manager for Laravel 12+ and 13: databases, files, AES-256 encryption, integrity manifests and multi-destination storage — with restore, retention, scheduling, queues and monitoring built in.

It is designed around composition over inheritance: every capability (dumping, compressing, encrypting, hashing, archiving, storing) is a small, replaceable unit behind an interface, so it is easy to test, extend and to build a UI on top of.

🇨🇿 Kompletní česká dokumentace: docs/cz. The badge URLs assume github.com/nyoncode/laravel-backup-manager — adjust if your repository lives elsewhere.

Table of contents

• Why this package
• Requirements
• Installation
• Quick start
• Core concepts
• What a backup contains
• The backup manifest
• Feature tour
  • Databases
  • Files
  • Compression
  • Encryption & integrity
  • Storage destinations
  • Restore (with rollback)
  • Retention
  • Scheduling & queues
  • Monitoring, history & notifications
  • AI assistants (MCP)
• CLI reference
• Programmatic API
• Architecture
• Testing
• Documentation
• License

Why this package

Most Laravel backup tools stop at "zip the app and push it to S3". Backup Manager goes further:

• Every backup is self-describing. A JSON manifest records the exact environment, drivers, archive checksum and a hash of every file — so a backup is verifiable and portable independently of this package.
• Safe restores. Restores verify integrity first, and by default take a pre-restore snapshot so a failed restore rolls back to the previous state.
• No arbitrary size limits. The archiver is a streaming TAR implementation with GNU extensions: no 8 GiB per-file limit, no 100-byte path limit, flat memory usage.
• Real multi-destination. Destinations are ordinary Laravel disks, so Local, S3, FTP, SFTP, Azure, B2 and WebDAV all work, and you can write to several at once.
• Production plumbing included. Queues, the scheduler (with withoutOverlapping), GFS retention, health monitoring, an operation-history table and mail/Slack notifications.

Requirements

Database dumps use the vendor CLI tools:

zstd compression needs the zstd binary. Remote disks may need their Flysystem adapter (e.g. league/flysystem-aws-s3-v3).

Installation

Publish the configuration:

Optionally publish and run the history migration (see Monitoring):

Full details: docs/installation.md.

Quick start

New to the package? The Getting started tutorial walks you from install to a verified, restorable backup in about ten minutes. Already set up? These are the everyday commands:

Core concepts

A profile lives in config/backup-manager.php:

Run a specific profile with --profile=name. See docs/configuration.md for every option.

What a backup contains

A single backup produces two objects on each destination:

Inside the (uncompressed, pre-encryption) archive:

The filename carries the profile, a timestamp and a short random suffix so two backups never collide, even within the same second.

The backup manifest

The manifest is the feature that makes a backup self-describing and verifiable. Because it is stored unencrypted next to the archive, you can inspect it and check the archive's checksum without downloading or decrypting the archive.

It never contains secrets — only which algorithms were used.

Feature tour

Databases

MySQL, MariaDB, PostgreSQL and SQLite. Choose connections, exclude tables, or keep only a table's structure:

Passwords are passed through the environment, never the command line. Details & the PostgreSQL client-version note: docs/databases.md.

Files

Multiple source roots, prefix/glob excludes, hidden-file and symlink handling:

Details: docs/files.md.

Compression

none, gzip, bzip2 or zstd, streamed so memory stays flat:

Encryption & integrity

Streaming AES-256 (CBC or authenticated GCM), SHA-256/512 checksums, and optional HMAC signing of the manifest (signing is a Pro feature — see Pro & the UI):

CBC streams (any size); GCM is authenticated but buffered in memory and capped by encryption.gcm_max_megabytes. Full guidance: docs/security.md.

Storage destinations

Any Laravel disk — write to several at once:

Local, S3-compatible, FTP, SFTP, Azure Blob, Backblaze B2, WebDAV. Setup examples: docs/storage.md.

Restore (with rollback)

Restores verify the archive against its manifest first. By default they take a pre-restore snapshot and roll everything back if the restore fails — files are written via a temporary file and atomic rename. Opt out with --unsafe. Details: docs/restore.md.

Retention

A simple keep-latest count (free core), or Grandfather-Father-Son and a total-size cap (Pro), plus an age cap:

Details: docs/retention.md.

Scheduling & queues

Enable the built-in schedule (registered with withoutOverlapping) and/or run backups on the queue:

With the queue enabled, backup:run dispatches a RunBackupJob; force a synchronous run with --sync. Details: docs/scheduling.md.

Monitoring, history & notifications · Pro

Pro. backup:monitor, the backup_history table and Slack notifications ship in Backup Manager Pro. The free core sends failure notifications by mail.

backup:monitor reports per-destination health and exits non-zero when unhealthy (so it doubles as an uptime check). Every operation is logged and, if the migration is published, stored in a backup_history table. Failures and unhealthy destinations can notify you by mail and/or Slack:

AI assistants (MCP)

Serves a Model Context Protocol server on stdin/stdout, so an AI assistant can read this installation — disks, database connections, dump binaries, the resolved profiles, the full configuration reference — then propose a configuration, write it, and prove it by running and verifying a real backup. No extra dependency; it ships with the free core.

Writes are bounded: only documented keys with values of the declared type, a dry run by default that also reports the findings the result would have, env()-backed settings routed to .env, comments in the config file preserved, and the previous file copied aside before an atomic write. Deleting backups is a separate destructive tool that stays hidden until you enable it, and restore is not exposed over MCP at all.

See docs/14-mcp.md.

Backup Manager Pro & the UI dashboard

This package is the free MIT core — a complete, CLI-first backup tool. Two commercial add-ons plug in through its contracts, with no code changes on your side:

• Backup Manager Pro adds incremental & deduplicated backups, GFS retention, HMAC manifest signing, health monitoring with history, and Slack notifications.
• Backup Manager UI is a live Livewire dashboard to run, browse, restore, verify and monitor every destination from one screen (requires Pro).

A licence holder upgrades in one command:

Full tier breakdown and the upgrade flow: docs/13-pro-and-ui.md.

CLI reference

Full flags and examples: docs/cli.md.

Programmatic API

The managers return typed value objects (BackupResult, RestoreResult, HealthReport, StoredBackup, Manifest) — ideal for a UI layer.

Architecture

A backup is a pipeline of small stages threaded through a shared BackupContext:

Each stage implements BackupStage and is injected into BackupManager, so you can add, remove or reorder stages without touching the core. Every capability sits behind an interface (DatabaseDumper, Compressor, Encryptor, Signer, Archiver, BackupRepository, RetentionStrategy) with a focused implementation. See docs/extending.md.

Testing

The integration suite runs real backup → restore round-trips against live MySQL, MariaDB, PostgreSQL and MinIO (S3). Point it at your own servers with the BM_* environment variables (see tests/Integration/DatabaseTestKit.php for the keys and defaults); any service that isn't reachable is skipped automatically, so composer test stays green without them.

CI (.github/workflows/tests.yml) runs:

• static-analysis — PHPStan level 8
• tests — Unit + Feature across the full support grid: Laravel 12 on PHP 8.3 / 8.4 / 8.5 and Laravel 13 on PHP 8.4 / 8.5, plus a lowest-dependencies leg
• windows — the platform-agnostic Unit suite on windows-latest
• integration — a matrix leg per engine (MySQL 8.4, MariaDB 11, PostgreSQL 16, MinIO/S3), each against its own real service container

Documentation

Roadmap

Where the package could go after 1.0 (incremental backups, restorability testing, a fully streamed pipeline and more): ROADMAP.md.

License

The MIT License (MIT). See LICENSE.