Laravel Stream Backup Laravel Package

Getting Started

Publish the package config and read it before touching any command — nearly every decision you'll make (disk, chunk size, encryption driver, retention) lives there, and the defaults are the ones the maintainers test against.

1. Install and publish: composer require ahmed-nour-dev/laravel-stream-backup, then publish the config and any migrations the installer reports. v1.8.0 adds no migrations and changes no defaults, so an install today starts you on the current behaviour with nothing to reconcile.
2. First read: open the published config and note two things — which filesystem disk the backups land on, and which encryptor is selected (openssl-aes-256-gcm or sodium). Everything else is tuning.
3. First use case: the small, boring one. Take a backup of a throwaway/dev database to a local or S3 disk, then restore it into a scratch database in the same session. Streaming backups are only proven by the restore path; a successful backup command that nobody has ever restored is not evidence of anything.
4. Check the wire format version in the artefact. v1.8.0 introduces wire format v2 for OpenSSL backups. Before you build tooling around the files, confirm which version your fresh backups are written as, because it dictates the minimum package version on every machine that will read them.

If you're upgrading an existing install rather than starting fresh, skip to the upgrade ordering rule in Gotchas and Tips before you take another backup — that ordering is the single most important operational fact in this release.

Implementation Patterns

Treat backup and restore as two separately deployed capabilities. The release makes this explicit: v1 backups still restore on v1.8.0, but v1.7.2 and earlier cannot read v2 backups. That means "can write" and "can read" have different version floors the moment you adopt v2. In practice: deploy the new version everywhere that might restore (production, staging, local dev VMs, that one CI cron job, the DR box nobody logs into), then start taking new backups.

Wrap the commands in your own artisan command or job. Don't sprinkle the vendor commands through deploy scripts and crontabs. Put a thin app/Console/Commands/BackupRun.php and a RestoreBackup.php around them, so the day you need to swap disks, add a post-backup checksum, or gate restores behind a confirmation prompt, you have one place to change. It also gives you a natural spot to log the wire format version alongside the backup filename.

Scheduled backups: one entry in routes/console.php/kernel schedule, withoutOverlapping(), and a failure notification. Streaming keeps memory flat, so you don't need to babysit chunk sizes on large databases — but you do want to know when a nightly run silently stops producing files. Add a "backup age" health check; it catches both failed runs and success-with-wrong-disk misconfigurations.

Restore drills, not restore plans. Schedule a recurring job that restores the latest backup into a scratch schema and runs a cheap integrity query (SELECT COUNT(*) on a couple of known tables). This is where v1.8.0 pays for itself: a truncated backup now fails loudly instead of restoring a partial dataset that looks complete. That only helps you if something is actually exercising the restore path on a schedule.

Verification on your side is now about identity, not integrity. Since the format authenticates the end of the stream, you no longer need to guess whether a file is complete. Keep storing a checksum/size alongside the artefact if you already do, but the authoritative "is this restorable" answer comes from attempting the restore. Point your alerting at the restore drill, not at file size heuristics.

Multi-environment disk strategy: local disk for dev, object storage for production, same config keys. When you test a format upgrade, test against the disk type you actually use in production — a stalled-download bug (exactly what #49/#50 fixed) is a network behaviour that a local-disk test will never reproduce.

Key management: the encryption key is the backup. Store it outside the backup disk, in your secrets manager, and version it. If you rotate keys, keep the old key material available for as long as old backups are retained, or you've simply deleted your backups with extra steps.

Gotchas and Tips

The upgrade ordering rule is non-negotiable. Upgrade every server that restores backups to v1.8.0+ before you take any v2 backup. Once a v2 backup exists, do not roll back below v1.8.0 — an older version will not be able to read it, and "roll back the release because something else broke" is exactly the moment you discover this. If your deploy process supports rollbacks, add a guard or a documented exception for this package.

Pin the package version in composer.json semantics you understand. A security release that changes the on-disk format is a strong argument for keeping this on a caret constraint you actually review on update, and for reading the changelog on every bump. Don't let composer update decide your backup compatibility.

Old backups are still v1 — and that's fine. Existing v1 backups continue to restore on v1.8.0. But be aware you're in a mixed-format window until retention rolls the old ones off. Any tooling that parses backups directly (rather than restoring through the package) must handle both versions, or you'll have a confusing "some backups fail to parse" bug that maps to file age.

Sodium is the low-friction path. Sodium backups get the same end-of-stream authentication without a format change, so if you have no hard requirement on AES-GCM, choosing sodium keeps you out of the version-skew problem entirely and simplifies any future rollback story. The trade-off is portability of the artefact outside PHP/libsodium — check that constraint before deciding.

Trailing bytes are now rejected. If any of your own scripts append metadata to a backup file (a tag, a newline, a manifest blob), those files will now fail to restore. Move sidecar metadata into a separate .meta/.json file next to the artefact. This is the most likely unexpected breakage from this release, and it will show up as a restore error on files that "used to work".

A stalled download mid-frame no longer breaks a valid restore. This was a real-world failure mode — flaky network, resumable/retried download, restore fails on a perfectly good backup. If your ops runbook contains "retry the download, then retry the restore," you can simplify it. Don't over-simplify to "auto-retry forever": the corruption detection is still the thing you rely on, so surface restore failures rather than swallowing them.

Debugging a failed restore, in order: (1) confirm the restorer's package version ≥ the file's wire format version; (2) confirm the encryption key matches the one used at backup time; (3) confirm nothing appended bytes to the file; (4) only then suspect the data. Steps 1 and 2 account for the overwhelming majority of "corrupt backup" reports, and both produce errors that don't obviously say "version" or "key".

Extension points: the encrypted stream is a wrapper around a plaintext stream — the natural place to hook in is outside the encryptor rather than by modifying the format. If you need replication or archival, do it on the finished artefact via the filesystem disk (S3 lifecycle rules, cross-region replication) rather than by intercepting the stream. Anything that touches the byte stream risks tripping the trailing-bytes check.

Test the failure you care about. Take a backup, truncate 10% off the end with head -c, and confirm the restore now fails with a clear error. That two-minute experiment tells you more about whether this release protects you than any amount of changelog reading — and it's the check most teams skip.