Send one notification on backup failure

[joshbonnick]

Fixes #1662

Summary

This PR addresses an issue with exception handling in BackupJob.

As both the BackupCommand command and BackupJob are handling exceptions the result is both send the failure notification when they deem the process to have failed.

With these changes BackupCommand will exclusively handle notifying the user if a failure scenario occurs. Due to the command being able to retry itself it makes the most sense to allow it to determine when it considers the process to have failed.

---

Before these changes the copyToBackupDestinations method of BackupJob would fire the backup failed event and pass the destination as a parameter.

laravel-backup/src/Tasks/Backup/BackupJob.php

Line 300 in f4a2abc

$this->sendNotification(new BackupHasFailed($exception, $backupDestination));

To ensure behavior remains the same, I have added the BackupFailed exception which acts as a decorator with a public $backupDestination property which is used to set the same property in the backup failed event.

The backup destination property is set by chaining on the exception.

laravel-backup/src/Tasks/Backup/BackupJob.php

Line 304 in c394924

throw BackupFailed::from($exception)->destination($backupDestination);

The notification receives the original exception for the user to debug.

laravel-backup/src/Commands/BackupCommand.php

Line 84 in dc70da6

? new BackupHasFailed($exception->getPrevious(), $exception->backupDestination)

Possible Concerns

• BackupJob still handles success notifications and informative (including error) output to the console, we would need to completely decouple the job from the command to change this behavior, which I do not believe has any benefit to the package.
• PHPStan raised an issue with getPrevious() returning Throwable|null as BackupHasFailed event accepts Exception - to fix this an @method has been added to BackupFailed. This can be replaced with a previous(): Exception method if you prefer.

[freekmurze]

Thanks!