v10: Breaking changes for PHP 8.4 and Laravel 12

[freekmurze]

Summary

This is the v10 major release branch. It requires PHP 8.4+ and Laravel 12+, and contains several breaking changes aimed at modernizing the codebase and addressing long-standing community requests.

Serializable events

All events now carry primitive data (string $diskName, string $backupName) instead of BackupDestination or BackupDestinationStatus objects. This means events can be safely used with queued listeners, which was previously impossible (#1860).

Breaking: If you listen to backup events, update your listeners to use $event->diskName and $event->backupName instead of $event->backupDestination.

Decoupled notifications from events

Events now always fire, even when --disable-notifications is used. Notifications are gated separately via EventHandler::enable() / EventHandler::disable(). This fixes the issue where BackupWasSuccessful was never fired with --disable-notifications (#1744), and also means encryption (which depends on the BackupZipWasCreated event) works correctly regardless of notification settings.

Replaced ConsoleOutput singleton with BackupLogger

The global consoleOutput() helper has been replaced by backupLogger(), which uses a listener pattern. Console output is registered as a listener in the base command, making it easy to add custom log destinations.

Notification discovery replaced with explicit map

EventHandler now uses an explicit $eventToNotificationMap array instead of string manipulation to find notification classes. Falls back to config-based discovery for custom notification classes.

Resilient multi-destination backups

Added continue_on_failure config option for backup destinations. When enabled, a failure on one destination won't abort the entire backup — it fires a BackupHasFailed event for the failed destination and continues. Only throws if all destinations fail (#1708, #1934, #1939).

Health check failure details

BackupDestinationStatus now collects all health check failures instead of stopping at the first one. UnhealthyBackupWasFound event carries a failureMessages collection. backup:monitor and backup:list commands display all failure reasons (#1509).

New enums

• Encryption enum (none, default, aes128, aes192, aes256) replaces the old mixed null/false/string/int encryption config
• DumpFilenameBase enum (database, connection) replaces stringly-typed config values

EncryptBackupArchive uses Config DTO

The encryption listener now receives the Config DTO via constructor injection instead of calling config() directly.

DefaultStrategy uses Config DTO

The default cleanup strategy now uses the typed Config DTO ($this->config->cleanup->defaultStrategy->keepAllBackupsForDays, etc.) instead of raw array access. The recursive removeOldBackupsUntilUsingLessThanMaximumStorage method was also replaced with a while loop.

New command options

• --filename-suffix= — Append a suffix to the backup filename (Backup:run Filename Append #1802)
• --exclude=* — Exclude additional directories/files at runtime (Include/exclude folders at runtime #1869)
• --destination-path= — Override the backup destination path at runtime (Unable to specify destination path on runtime #1900)

Graceful handling of missing directories

FileSelection now warns via backupLogger() instead of failing when an included directory doesn't exist (#1671).

Default excludes

storage/framework is now excluded by default (#1325).

Backup verification

New verify_backup config option. When enabled, the zip archive is opened after creation to verify it's valid and non-empty.

Generic webhook notification channel

New webhook notification channel that POSTs JSON to a configurable URL. Works with Mattermost, Microsoft Teams, or any custom integration (#1711). All notification classes now include a toWebhook() method.

Breaking changes

• PHP 8.4+ required
• Laravel 12+ required
• All events changed from carrying domain objects to carrying primitive data
• consoleOutput() helper replaced by backupLogger()
• ConsoleOutput class removed
• BackupJob::disableNotifications() removed — use EventHandler::disable() instead
• CleanupJob no longer accepts $sendNotifications — events always fire
• CleanupStrategy constructor changed from Repository $config to Config $config
• DefaultStrategy changed from raw array config to typed Config DTO
• Encryption config values changed from null/false/'default' to enum strings ('none', 'default', 'aes128', etc.)
• BackupDestinationStatus::getHealthCheckFailure() replaced by getHealthCheckFailures() (collection)