feat: add job failure callbacks to batches

Author: Yitz Willroth

src/Illuminate/Bus/Batch.php

@@ -101,18 +101,19 @@ class Batch implements Arrayable, JsonSerializable
     /**
      * Create a new batch instance.
      *
-     * @param  \Illuminate\Contracts\Queue\Factory  $queue
-     * @param  \Illuminate\Bus\BatchRepository  $repository
-     * @param  string  $id
-     * @param  string  $name
-     * @param  int  $totalJobs
-     * @param  int  $pendingJobs
-     * @param  int  $failedJobs
-     * @param  array  $failedJobIds
-     * @param  array  $options
-     * @param  \Carbon\CarbonImmutable  $createdAt
-     * @param  \Carbon\CarbonImmutable|null  $cancelledAt
-     * @param  \Carbon\CarbonImmutable|null  $finishedAt
+     *
+     * @param \Illuminate\Contracts\Queue\Factory $queue
+     * @param \Illuminate\Bus\BatchRepository $repository
+     * @param string $id
+     * @param string $name
+     * @param int $totalJobs
+     * @param int $pendingJobs
+     * @param int $failedJobs
+     * @param array $failedJobIds
+     * @param array $options
+     * @param \Carbon\CarbonImmutable $createdAt
+     * @param \Carbon\CarbonImmutable|null $cancelledAt
+     * @param \Carbon\CarbonImmutable|null $finishedAt
      */
     public function __construct(
         QueueFactory $queue,
@@ -225,8 +226,8 @@ public function processedJobs()
      * Get the percentage of jobs that have been processed (between 0-100).
      *
      * @return int
-     */
-    public function progress()
+     **/
+    public function progress(): int
     {
         return $this->totalJobs > 0 ? round(($this->processedJobs() / $this->totalJobs) * 100) : 0;
     }
@@ -236,38 +237,39 @@ public function progress()
      *
      * @param  string  $jobId
      * @return void
-     */
+     **/
     public function recordSuccessfulJob(string $jobId)
     {
         $counts = $this->decrementPendingJobs($jobId);
 
         if ($this->hasProgressCallbacks()) {
-            $batch = $this->fresh();
-
-            (new Collection($this->options['progress']))->each(function ($handler) use ($batch) {
-                $this->invokeHandlerCallback($handler, $batch);
-            });
+            $this->invokeCallbacks('progress');
         }
 
         if ($counts->pendingJobs === 0) {
             $this->repository->markAsFinished($this->id);
         }
 
         if ($counts->pendingJobs === 0 && $this->hasThenCallbacks()) {
-            $batch = $this->fresh();
-
-            (new Collection($this->options['then']))->each(function ($handler) use ($batch) {
-                $this->invokeHandlerCallback($handler, $batch);
-            });
+            $this->invokeCallbacks('then');
         }
 
         if ($counts->allJobsHaveRanExactlyOnce() && $this->hasFinallyCallbacks()) {
-            $batch = $this->fresh();
+            $this->invokeCallbacks('finally');
+        }
+    }
+
+    /**
+     * Invoke the callbacks of the given type.
+     */
+    public function invokeCallbacks(string $type, ?\Throwable $e = null): void
+    {
+        $batch = $this->fresh();
 
-            (new Collection($this->options['finally']))->each(function ($handler) use ($batch) {
-                $this->invokeHandlerCallback($handler, $batch);
+        (new Collection($this->options[$type]))
+            ->each(function ($handler) use ($batch, $e) {
+                $this->invokeHandlerCallback($handler, $batch, $e);
             });
-        }
     }
 
     /**
@@ -338,36 +340,30 @@ public function hasFailures()
      * @param  \Throwable  $e
      * @return void
      */
-    public function recordFailedJob(string $jobId, $e)
+    public function recordFailedJob($jobId, $e)
     {
         $counts = $this->incrementFailedJobs($jobId);
 
         if ($counts->failedJobs === 1 && ! $this->allowsFailures()) {
             $this->cancel();
         }
 
-        if ($this->hasProgressCallbacks() && $this->allowsFailures()) {
-            $batch = $this->fresh();
+        if ($this->allowsFailures()) {
+            if ($this->hasProgressCallbacks()) {
+                $this->invokeCallbacks('progress', $e);
+            }
 
-            (new Collection($this->options['progress']))->each(function ($handler) use ($batch, $e) {
-                $this->invokeHandlerCallback($handler, $batch, $e);
-            });
+            if ($this->hasFailureCallbacks()) {
+                $this->invokeCallbacks('failure', $e);
+            }
         }
 
         if ($counts->failedJobs === 1 && $this->hasCatchCallbacks()) {
-            $batch = $this->fresh();
-
-            (new Collection($this->options['catch']))->each(function ($handler) use ($batch, $e) {
-                $this->invokeHandlerCallback($handler, $batch, $e);
-            });
+            $this->invokeCallbacks('catch', $e);
         }
 
         if ($counts->allJobsHaveRanExactlyOnce() && $this->hasFinallyCallbacks()) {
-            $batch = $this->fresh();
-
-            (new Collection($this->options['finally']))->each(function ($handler) use ($batch, $e) {
-                $this->invokeHandlerCallback($handler, $batch, $e);
-            });
+            $this->invokeCallbacks('finally');
         }
     }
 
@@ -402,6 +398,16 @@ public function hasFinallyCallbacks()
         return isset($this->options['finally']) && ! empty($this->options['finally']);
     }
 
+    /**
+     * Determine if the batch has "failure" callbacks.
+     *
+     * @return bool
+     */
+    public function hasFailureCallbacks()
+    {
+        return isset($this->options['failure']) && ! empty($this->options['failure']);
+    }
+
     /**
      * Cancel the batch.
      *
@@ -446,8 +452,8 @@ public function delete()
      * Invoke a batch callback handler.
      *
      * @param  callable  $handler
-     * @param  \Illuminate\Bus\Batch  $batch
-     * @param  \Throwable|null  $e
+     * @param \Illuminate\Bus\Batch $batch
+     * @param \Throwable|null $e
      * @return void
      */
     protected function invokeHandlerCallback($handler, Batch $batch, ?Throwable $e = null)

src/Illuminate/Bus/PendingBatch.php

@@ -237,14 +237,23 @@ public function finallyCallbacks()
     }
 
     /**
-     * Indicate that the batch should not be cancelled when a job within the batch fails.
-     *
-     * @param  bool  $allowFailures
-     * @return $this
+     * Indicate that the batch should not be cancelled when a job within the batch fails;
+     * optionally add callbacks to be executed upon each job failure (this may be useful for
+     * running other jobs when a job fails).
      */
-    public function allowFailures($allowFailures = true)
+    public function allowFailures(bool|callable|Closure|array $param = true): self
     {
-        $this->options['allowFailures'] = $allowFailures;
+        if (! is_bool($param)) {
+            $param = Arr::wrap($param);
+
+            foreach ($param as $callback) {
+                $this->options['failure'][] = $callback instanceof Closure
+                    ? new SerializableClosure($callback)
+                    : $callback;
+            }
+        }
+
+        $this->options['allowFailures'] = (bool) $param;
 
         return $this;
     }
@@ -259,6 +268,14 @@ public function allowsFailures()
         return Arr::get($this->options, 'allowFailures', false) === true;
     }
 
+    /**
+     * Get the "failure" callbacks that have been registered with the pending batch.
+     */
+    public function failureCallbacks(): array
+    {
+        return $this->options['failure'] ?? [];
+    }
+
     /**
      * Set the name for the batch.
      *