- How do I install Capsule in a Laravel application?
- Install it with Composer using composer require dgtlss/capsule, then publish the package configuration with php artisan vendor:publish and point it at your database connections and target filesystem disks. After that, register the backup command on Laravel's scheduler so full and incremental runs happen automatically. Because Capsule is a Laravel-native package, it uses your existing filesystem abstraction rather than its own storage drivers, so any disk you have configured can be a backup target.
- Which Laravel and PHP versions does Capsule support?
- Capsule v3 targets Laravel 12 on PHP 8.2 and Laravel 13 on PHP 8.3. That means Laravel 10, Laravel 11, and PHP 8.1 are no longer supported, so adoption is all-or-nothing rather than something you can partially phase in. If your application is still on an older framework version, the framework upgrade itself is the real project and should be planned with its own risk assessment before Capsule is added.
- What PHP extensions does Capsule require for backups and restores?
- You need zip, sodium, and zlib available, plus pdo_sqlite for SQLite backup and validation and sqlite3 for SQLite restore. The legacy ZIP path also expects a libzip build with AES support. Requirements are not identical across backup, validation, and restore, so verify every environment that might perform a restore, including your incident-response tooling, before you rely on the package.
- Can I decrypt and restore a Capsule backup without a working Laravel application?
- Yes. Capsule ships a standalone capsule-decrypt utility that unlocks archives with the password alone, so recovery does not depend on a healthy Laravel app, a working deploy, or a readable backup catalog. This is the strongest disaster-recovery feature in v3 because it decouples restoration from application state. Keep a version-pinned copy of the decryptor available for as long as you retain any archive it must open, since the .capsule.enc format is package-specific.
- How does Capsule handle encryption keys and backup password rotation?
- Backups are encrypted with a password you supply, and that password becomes a first-class operational secret rather than a config detail. Store it in a vault or escrow arrangement with a documented owner and rotation policy, because changing the password or encryption settings causes the next run to start a fresh full base. Treat key custody and rotation as engineering deliverables owned by the platform team, not as a setting a single developer keeps in a .env file.
- Why did Capsule start a new full backup instead of an incremental?
- Incremental chaining is checksum-bound to the existing chain, so changes to snapshot metadata, encryption settings, or the backup password force the next run to regenerate a full base. That is expected behavior, but it can be a storage and cost surprise on large datasets. Always keep full and incremental archives together as documented, because a fragmented chain cannot be restored on its own.
- How do retention policies work and how much storage should I plan for?
- Capsule prunes archives according to a retention window you configure, but that window must be longer than your oldest full base plus every incremental that depends on it. Because a full regeneration can be triggered by configuration changes, budget headroom for occasional duplicate fulls rather than assuming steady incremental growth. Also remember that no local archive does not mean no local disk: SQLite snapshots and filesystem adapters can still consume temporary staging space at peak.
- Is upgrading to Capsule v3 safe, and what changed?
- The upgrade is all-or-nothing because v3 drops Laravel 10 and 11 along with PHP 8.1, so the streaming and encryption improvements cannot be adopted piecemeal. The most consequential behavioral change is that new-format restores preserve named or numbered file-root directories, so any scripted restore path from a previous version may land files in different locations. Validate your restore scripts against a real archive after upgrading, since a layout mismatch can still pass a superficial validity check.
- How do I test that a Capsule backup can actually be restored?
- Run scheduled restore rehearsals into a disposable environment rather than trusting a green backup log, because a backup nobody can restore is an organizational failure, not a library bug. Confirm that the rehearsal environment has sodium, sqlite3, and the AES-capable libzip build, since an environment that can validate an archive may still be unable to restore it. Track restore time against your stated RTO and confirm the incremental chain covers your largest dataset within your RPO.
- How does Capsule compare to spatie/laravel-backup?
- Capsule differentiates itself with encrypted archives, checksum-bound incremental chaining, retention policies, notifications, and a standalone capsule-decrypt utility for recovery outside a running application. The tradeoff is format coupling: archives require a compatible Capsule installation or a pinned decryptor binary, and environment requirements are stricter than a simple scheduled dump. Choose Capsule when you need a defensible production disaster-recovery component and can own key custody and restore rehearsal; choose a simpler dumper when you only need convenience backups.