Laravel Backup Manager Laravel Package

Product Decisions This Supports

• Upgrade urgency / risk triage. v1.3.0 fixes a silent data-loss defect: retention was evaluated against every backup in the destination path rather than the profile that owned it. Because path defaults to backups for all profiles, the default multi-profile-on-one-disk arrangement meant a nightly backup:clean under one profile could prune another profile's fortnightly fulls, with nothing reported. If we run more than one profile on a shared disk, this is a patch-worthy correctness fix, not a nice-to-have — it directly invalidates any retention or RPO commitment we've made on paper.
• Retention/compliance guarantee as a sellable or auditable property. "keep_latest = N actually holds, per profile" is the kind of statement that survives an audit or a customer security questionnaire. The new StoredBackup::$profile / belongsTo() and CleanupReport turn retention from an implicit side effect into something we can report on and evidence.
• Migration sequencing is part of the fix, not an afterthought. Backups whose manifest predates the profile tag (or can't be read) are attributed to whichever profile is asking. So the first cleanup after upgrade can still prune a neighbouring profile's pre-existing backups — the old behaviour survives one run. That makes "upgrade" a small project with an ordering: upgrade, backup:clean --dry-run per profile to confirm the keep-set, then let the real cleaner run. Cheap, but it needs a ticket, not a footnote.
• Operational architecture: web vs. worker. Queued backup:clean (with --sync escape hatch, and --dry-run deliberately never queued) removes an unbounded-memory, invisible-to-failed_jobs job from the scheduler process on the web node. This is a reliability decision we can make without new infrastructure — it makes cleanup observable in the queue dashboard we already have. Same logic applies to the empty queue.queue fallback: we stop dispatching onto a queue name no worker listens on.
• Restore as a first-class workflow. queue.restore_timeout acknowledges that restores (download, decrypt, unpack, pre-restore snapshot) outlast backups. Supports deciding whether restore is a "run it and watch" operation or a genuine self-service/DR capability.
• Build vs. buy on retention plumbing. CleanupManager collapses four divergent copies (CLI, queue, dashboard, MCP tool) into one policy application point. That's a maintainability argument for staying on the package rather than growing our own wrapper — and it means our dashboard/MCP surfaces can't drift from CLI semantics.
• Roadmap sequencing for internal tooling. Profile-scoped listings (backup:list, backup:verify, backup:restore) change what operators see. Any runbook, support script, or internal admin UI that assumed a flat list of everything on a destination needs a revisit — schedule that with the upgrade, not after it.
• Ecosystem/lifecycle planning. Pest 5 support gated on PHP 8.4 / Symfony 8 means Laravel 13 is the trigger for a test-tooling major. Useful input to a framework-upgrade budget conversation.

When to Consider This Package

Adopt (or upgrade to ≥ v1.3.0) when:

• We run more than one backup profile on the same disk — the exact configuration this release fixes. Prior versions cannot be trusted to honour per-profile retention here.
• We need per-profile retention to be a real guarantee (customer commitments, SOC2-style evidence, internal SLAs) rather than a best-effort.
• Backups are scheduled on web nodes without dedicated workers, or cleanup cost is growing with blob-pool size — queued cleanup plus CleanupManager centralisation is the cleaner operating model.
• We plan to expose backups through more than one surface (CLI, dashboard, MCP/agent tooling) and want them to agree by construction.
• Restores are expected to be routine or self-service, where a distinct restore_timeout matters.

Look elsewhere or defer when:

• We only ever run a single profile per disk — the headline fix is latent for us, so upgrade cadence can follow normal maintenance rather than an emergency. (Legacy untagged manifests are then a non-issue, since there's only one owner.)
• We rely on a custom SnapshotDriver and cannot absorb a signature change (the new optional ?string $profile parameter must be added) — cost is small but it is a code change, and null preserves the old whole-path behaviour, so a driver left unfixed keeps the old, now-incorrect, semantics silently. Budget the edit.
• We need cross-profile visibility by design (e.g. one operator view over everything on a shared destination). Profile-scoped listings are the new contract; we'd need our own aggregate view on top.
• We have pre-upgrade backups we can't re-tag and multiple profiles sharing a destination and no appetite for a verified dry-run before the first real cleanup — in that window the old cross-profile deletion is still reachable.
• Our backup estate is database-only and small enough that a scheduled mysqldump plus object storage versioning covers it — the profile/destination/retention model is more machinery than the problem warrants.

How to Pitch It (Stakeholders)

To executives: This release closes a silent data-loss bug. Where two backup schedules shared a disk — the package's default layout — one schedule's cleanup could delete the other's backups without any error, so a stated retention promise could quietly not be met. After v1.3.0, every backup is tagged with the schedule that created it, retention counts and deletes only its own, and cleanup produces a report we can point at. We should upgrade on a maintenance window rather than wait for the next routine bump, because the risk window is "any night the cleaner runs." There is one ordering caveat: backups written before the upgrade carry no tag and are still attributed to whoever is cleaning, so the first post-upgrade cleanup is verified with a dry run rather than assumed.

To engineering: Four things to action. (1) Upgrade and confirm per-profile retention actually holds in our environment — this is a behaviour change, so verify rather than assume. (2) Before the first real backup:clean, run --dry-run per profile: pre-upgrade (untagged or unreadable-manifest) backups are counted as the asking profile's, so the old cross-profile pruning is still reachable exactly once. (3) Any custom SnapshotDriver needs the new optional ?string $profile parameter in applyRetention(); leaving it out keeps the old whole-path behaviour, which is now the wrong answer. (4) backup:list / backup:verify / backup:restore are profile-scoped now, so anything parsing or paging those outputs needs a look. On the upside: cleanup can go to the queue (BACKUP_QUEUE=true, --sync to force inline, --dry-run never queues), restores get their own queue.restore_timeout, and four copies of the retention sequence are now one CleanupManager, so CLI, dashboard and MCP can't drift. Empty queue.queue also no longer dispatches to a queue name no worker listens on. Tests are on Pest 4, with Pest 5 arriving alongside Laravel 13 / PHP 8.4.