Tomato Backup Module Laravel Package

Technical Evaluation

Architecture fit

tomatophp/tomato-backup-module is a thin orchestration and presentation layer: it wraps spatie/laravel-backup behind a Filament admin panel so operators can create, list, download, and delete database/file backups without touching artisan. That shape is favorable from a product-risk standpoint — the hard, failure-prone problems (dump/restore mechanics, retention, storage drivers) are delegated to a mature upstream library rather than reimplemented by a single-maintainer project. The module's own value-add is the admin surface and scheduling convenience.

Fit is therefore contingent, not intrinsic. It is a strong fit only where we are already on the TomatoPHP/Filament stack (tomato-admin, tomato-settings, roles/permissions). Outside that ecosystem it is a UI over an artisan command, and the dependency cluster (Filament + Spatie + TomatoPHP glue) costs more than the panel is worth.

Integration feasibility

Composer-installable with the standard service-provider + publishable-config pattern. The real wiring work is Filament panel registration plus migrations for the backup/monitor tables. For a team already on Filament v3 this is a days-scale spike, not a sprint. Feasibility falls off sharply on Filament v2, non-Filament admin surfaces, or API-only services — where the UI value evaporates and only the scheduler config remains, at which point we should configure Spatie directly.

Technical risk

• v1.0.0 is an availability signal, not an evidence base. The release notes are a bare changelog link — no feature enumeration, no migration notes, no breaking-change declaration. We cannot determine whether the 0.x → 1.0.0 jump renamed config keys, altered table schemas, or bumped Filament APIs. Treat the compatibility matrix as unknown, not stable.
• Backup correctness is a production-data risk, not a feature risk. Failures are silent until a restore is attempted, so the quality bar is whether the module surfaces failure (disk full, DB dump timeout, absent queue worker), not whether the buttons render.
• Ecosystem coupling is hard-pinned. Spatie major and Filament major are both upstream constraints; TomatoPHP packages historically track Filament releases with lag, so the next Filament major is a probable forced-upgrade event we don't control.
• Maintainer concentration. Zero stars, zero dependents, single vendor, last release March 2024. Bus factor and abandonment risk are material for a component sitting in the disaster-recovery path — mitigated only by the fact that the engine underneath (Spatie) is replaceable-independent of the UI.

Key questions

1. Which spatie/laravel-backup and Filament majors does v1.0.0 pin, and are the constraints caret or exact?
2. What changed between the last 0.x and v1.0.0 — config schema, migrations, namespaces?
3. Does the UI honor --only-db / --only-files and monitor-tag semantics, or bypass them?
4. Where do backups land by default, and is the destination pluggable without forking?
5. Is there CI that exercises an actual backup and restore cycle, or only backup?
6. What is the fork/patch cost if upstream stalls — is the module small enough that we can own it?

Integration Approach

Stack fit

Target: Laravel 10/11 + Filament 3 + PHP 8.1+ in a TomatoPHP-flavored admin panel. Explicit non-fits: API-only services, non-Filament admin UIs, and teams already covered by a managed service (AWS Backup, Snapshooter, PlanetScale PITR) — in those cases the module duplicates coverage and should be declined rather than layered in.

Migration path

Greenfield evaluation, not an upgrade. Recommended path: install in a non-production environment, point the destination at a throwaway S3 bucket or a local storage/app/backups path, run one backup, then restore it into a scratch database and diff row counts on two or three critical tables. Pin the exact version ("tomatophp/tomato-backup-module": "1.0.0") rather than floating a caret until the changelog gap is closed. Keep spatie/laravel-backup config as the source of truth; let the module supply only scheduling and UI.

Compatibility

Gate merge on: Laravel constraint, PHP constraint, Filament major, Spatie backup major, and whether the module publishes its own migrations or reuses Spatie's monitor tables. Confirm the queue driver — backups belong on a queue, and a database queue without a running worker in every environment (including staging) means backups silently never fire.

Sequencing

1. Spike in a branch: install, register the panel, run one successful backup.
2. Prove restore before proving scheduling — restore is the only test that matters.
3. Move destination credentials into the secret store; never commit the published config with keys.
4. Wire scheduling through the Laravel scheduler; confirm backup:monitor health checks feed existing alerting.
5. Staging for a full week including at least one failure injection (revoke S3 permissions) to verify alerting.
6. Production cutover with the existing backup mechanism retained for one full retention cycle as fallback.
7. Document the underlying artisan commands as a manual fallback so a UI outage never blocks recovery.

Operational Impact

Maintenance

Low code maintenance, non-zero version-chasing. Upgrade cadence is bound to Filament and Spatie majors — expect one or two forced upgrades per year plus potential vendor/fork work if the module lags a Filament release by more than a quarter. Budget it as a dependency-ownership line item, not a one-time install.

Support

Community-only, single-vendor, no SLA. Acceptable for internal tooling; questionable for a disaster-recovery component unless the team can read and patch the source. The mitigant is architectural, not contractual: keep Spatie's commands documented and runnable so the UI is never a single point of failure for recovery.

Scaling

Backups scale with database size, not request volume. Two hard limits surface early: PHP/CLI execution time on dumps above a few GB, and disk I/O contention when dumping during peak traffic. Large databases require splitting --only-db from file backups, off-peak scheduling, and a destination supporting multipart upload. The Filament listing page degrades with long backup history — retention pruning is mandatory, not optional.

Failure modes

• Silent non-execution — scheduler off, queue worker down, onOneServer misconfigured. Most common, most dangerous.
• Silent partial success — dump succeeds, upload fails; the record looks healthy, the artifact is absent. Verify the module marks upload failures explicitly.
• Destination credential expiry — rotating S3 keys fail only in logs.
• Disk exhaustion on the local staging path for large dumps.
• Retention misconfiguration — pruning deletes the only good copy, or never deletes and fills the bucket.
• Untested restore — the dominant real-world failure: everything looks fine until recovery is attempted.

Ramp-up

Half a day for a Laravel/Filament developer to install, configure, and run a backup. The real cost is process, not code: a named owner for the restore drill, alert routing, and retention policy. Recommend a documented quarterly restore rehearsal and a dashboard tile exposing last-successful-backup age as the primary health signal.

Product position: approve the approach — a cheap accelerator for admin-panel backup visibility — while gating the version behind the compatibility questions and a proven restore. Do not let this package define any RPO/RTO or audit commitment; those live in our own spec, and the module is swappable beneath them.