Capsule Laravel Package

Technical Evaluation

Architecture fit Capsule is a Laravel-native backup and disaster-recovery package: it drives backups of database and filesystem state through Laravel's filesystem abstraction and a scheduled/CLI surface, with encryption and restore tooling attached. v3.0.0 moves it from "convenient scheduled dump" toward "defensible production DR component," but only if we treat key custody and restore rehearsal as first-class engineering deliverables rather than package configuration. Architecturally this belongs to the platform/infrastructure domain (SRE-adjacent ownership), not to individual feature teams — a backup nobody can restore is an org problem, not a library problem.

Integration feasibility The blocking constraints are environmental, not code-level: PHP 8.2 (Laravel 12) or 8.3 (Laravel 13), plus zip, sodium, zlib extensions, pdo_sqlite for SQLite backup/validation, sqlite3 for SQLite restore, and an AES-capable libzip build for the legacy ZIP path. Feasibility therefore reduces to a question about our base images and CI runners: if we own the Dockerfiles, this is a small, well-understood change; if we run on a managed platform with a fixed extension set, this may be a hard blocker.

The genuinely valuable capability here is capsule-decrypt. Recovery no longer depends on a working Laravel application or backup catalog, which decouples DR from deploy state and from application health. That is the strongest architectural improvement in the release and the basis on which a TPM can justify adoption.

Technical risk

• Format coupling despite portability. .capsule.enc is a package-specific format requiring "a compatible Capsule installation" plus the password. The standalone decryptor reduces app coupling but does not eliminate tool coupling — we must retain a working decryptor binary, version-pinned, for as long as any archive in retention exists.
• Silent full-base regeneration. Changes to snapshot metadata, encryption settings, or passwords can cause the next incremental to start a fresh full base. This is a storage-and-cost surprise, and it fragments the chain unless full and incremental archives are kept together as documented.
• All-or-nothing upgrade. Dropping Laravel 10/11 and PHP 8.1 means we cannot partially adopt the streaming/encryption features without first clearing a framework upgrade with its own independent blast radius.
• Restore layout change. New-format restores preserve named or numbered file-root directories. Any scripted or automated restore path from a prior version may now land files in different locations — high consequence, and validation may not catch a layout mismatch that is nonetheless "valid."
• "No local archive" is not "no local disk." SQLite snapshots and filesystem adapters may still consume temporary staging space; capacity planning cannot assume otherwise.
• Environment asymmetry. Extension requirements differ between backup, validation, and restore. A restore environment that can validate may still be unable to restore.

Key questions

• Who owns the backup password — vault, escrow, or human? What is the rotation policy, and do we accept that rotation triggers a new full base?
• What are our stated RTO/RPO targets, and does checksum-bound incremental chaining actually satisfy them for our largest dataset?
• Do we already run Laravel 12+/PHP 8.2+, or does this release force a framework upgrade? If the latter, that upgrade is the real project.
• Can we install sodium, sqlite3, and an AES-capable libzip into every environment that might perform a restore — including the incident-response environment?
• Where does capsule-decrypt live, and how is its version pinned against archive format versions we still retain?
• How much temporary staging space do our adapters and SQLite snapshots actually need at peak?
• Does our remote storage backend tolerate streaming chunk writes (multipart limits, object-size caps, request timeouts)?
• What is the retention window for legacy ZIP archives, and therefore how long must the older toolchain remain operational?

Integration Approach

Stack fit Conditional and decidable. Strong fit if we own our container images and are on Laravel 12+/PHP 8.2+. Poor fit if we are pinned to Laravel 10/11, PHP 8.1, or a managed runtime where we cannot control extensions or the libzip build. The conditional is a two-hour check of base images and CI matrices, not a research project — do it before any design work.

Migration path Stage it, and exploit the fact that existing backups need no conversion:

1. Inventory — confirm PHP/Laravel floors and extension availability in build images, runtime images, CI runners, and the DR/incident-response environment (four places, not one).
2. Upgrade in non-production only — verify existing ZIP-format backups continue to produce and validate unchanged. This is the low-risk, reversible step.
3. Exercise the new safeguards — enable improved incrementals, then rehearse restore using --list and --dry-run before any real destination mutation, and diff the resulting layout against expectations from the prior version.
4. Pilot streaming encryption — --no-local --encrypt on one low-risk service with a documented password stored outside the application.
5. Standardize and document — publish the runbook, including the standalone decryption procedure and its plaintext-ZIP handling warning.

Compatibility Pin the package version and, separately and explicitly, pin the decryptor version against the archive format versions we retain. During the transition we will be running two toolchains concurrently: v3.x for new archives and the prior release (or an older decryptor) for archives still inside retention. That concurrent-support burden is the main compatibility cost and should be scheduled, not discovered.

Sequencing Prerequisites strictly precede adoption: framework/PHP upgrade → image extension work (including AES-capable libzip) → secret storage for the backup password → staging capacity → restore rehearsal harness → runbook. Do not let the package upgrade and the framework upgrade land in the same change window; they have independent failure signatures and would be indistinguishable during triage.

Operational Impact

Maintenance Low change frequency, high consequence. Steady-state maintenance is dominated by environment drift — base-image rebuilds that silently drop an extension, libzip rebuilt without AES, PHP minor upgrades — rather than by the package itself. Archive format is now tied to tool version, so package upgrades require a compatibility decision, not a routine composer update. Budget one recurring owner, not a rotating volunteer.

Support Two distinct runbooks with very different exercise frequency: backup is routine and should be silent (alert only on failure or on unexpected full-base creation); restore is rare and must be rehearsed on a schedule. Decryption is a separate competency with a separate artifact — the docs explicitly require keeping the password and recovery dependencies available separately from the application. That is an operational control we must actually implement (escrow, access logging, break-glass procedure), not merely agree with in a design review.

Scaling Streaming materially reduces peak local disk versus staging a complete local archive, which is the right shape for growing datasets. But peak temp usage from SQLite snapshots and filesystem adapters still governs capacity, and a forced fresh full base temporarily roughly doubles storage for that dataset. Encryption adds CPU on the sodium path; measure it against the largest real dataset rather than assuming it is negligible. Incremental chains also grow unbounded unless retention is defined.

Failure modes

• Password loss or mishandled rotation → archives are unrecoverable; because streaming archives are not openable with ordinary ZIP tools there is no ad-hoc rescue path. Highest-severity, lowest-frequency.
• Forced full base after metadata or encryption change → unexpected storage/cost spike and chain confusion at exactly the moment someone is troubleshooting something else.
• Restore layout drift → files land in different roots than scripts expect; validation passes, application is subtly broken. Most likely to be discovered late.
• Missing extension in the restore environment (sqlite3, AES-capable libzip) → discovered during an incident, which is the worst possible time.
• Temp-space exhaustion mid-backup → truncated archive; validation helps only if failures are surfaced to a human rather than logged and forgotten.
• Archive/decryptor version skew → the archive exists and the password is known, but the tool that reads it is gone.

Ramp-up Developer learning curve is genuinely low — this is configuration plus a scheduled command. The real effort is procedural: DR runbook authoring, rehearsal cadence, password custody and escrow, and an explicit decision on how long we retain both legacy archives and their toolchain. Rough shape for planning: image/extension work is small (days), runbook and first rehearsal are moderate (one to two weeks including a real restore into a scratch environment), and organizational agreement on key custody is the long pole and should be started first because it gates everything else.