Add retryWithDelay() and retryUntil() methods to Queueable trait

src/Illuminate/Bus/Queueable.php

@@ -49,6 +49,20 @@ trait Queueable
      */
     public $delay;
 
+    /**
+     * The number of seconds to wait before retrying a job that encountered an uncaught exception.
+     *
+     * @var \DateTimeInterface|\DateInterval|array|int|null
+     */
+    public $backoff;
+
+    /**
+     * The timestamp indicating when the job should timeout.
+     *
+     * @var \DateTimeInterface|int|null
+     */
+    public $retryUntil;
+
     /**
      * Indicates whether the job should be dispatched after all database transactions have committed.
      *
@@ -206,6 +220,36 @@ public function withoutDelay()
         return $this;
     }
 
+    /**
+     * Set the number of seconds to wait before retrying a job that encountered an uncaught exception.
+     *
+     * @param  \DateTimeInterface|\DateInterval|array|int  $delays
+     * @return $this
+     */
+    public function retryWithDelay($delays)
+    {
+        $this->backoff = $delays;
+
+        return $this;
+    }
+
+    /**
+     * Set the timestamp indicating when the job should timeout.
+     *
+     * @param  \DateTimeInterface|int|null  $datetime
+     * @return $this|\DateTimeInterface|int|null
+     */
+    public function retryUntil($datetime = null)
+    {
+        if (func_num_args() === 0) {
+            return $this->retryUntil;
+        }
+
+        $this->retryUntil = $datetime;
+
+        return $this;
+    }
+
     /**
      * Indicate that the job should be dispatched after all database transactions have committed.
      *

tests/Bus/QueueableTest.php

@@ -2,7 +2,10 @@
 
 namespace Illuminate\Tests\Bus;
 
+use Carbon\Carbon;
 use Illuminate\Bus\Queueable;
+use Illuminate\Container\Container;
+use Illuminate\Queue\SyncQueue;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 
@@ -65,6 +68,205 @@ public function testAllOnQueue(mixed $queue, ?string $expected): void
         $this->assertSame($job->queue, $expected);
         $this->assertSame($job->chainQueue, $expected);
     }
+
+    public static function retryWithDelayDataProvider(): array
+    {
+        $datetime = Carbon::now()->addHour();
+        $interval = new \DateInterval('PT1H');
+
+        return [
+            'integer' => [60, 60],
+            'array of integers' => [[10, 30, 60, 120], [10, 30, 60, 120]],
+            'DateTimeInterface' => [$datetime, $datetime],
+            'DateInterval' => [$interval, $interval],
+        ];
+    }
+
+    #[DataProvider('retryWithDelayDataProvider')]
+    public function testRetryWithDelay(mixed $delays, mixed $expected): void
+    {
+        $job = new FakeJob();
+        $result = $job->retryWithDelay($delays);
+
+        if ($expected instanceof \DateTimeInterface && $job->backoff instanceof \DateTimeInterface) {
+            $this->assertEquals($expected->getTimestamp(), $job->backoff->getTimestamp());
+        } elseif ($expected instanceof \DateInterval && $job->backoff instanceof \DateInterval) {
+            $this->assertEquals($expected->format('%R%Y%M%D%H%I%S'), $job->backoff->format('%R%Y%M%D%H%I%S'));
+        } else {
+            $this->assertSame($job->backoff, $expected);
+        }
+        $this->assertSame($result, $job);
+    }
+
+    public static function retryUntilDataProvider(): array
+    {
+        $datetime = Carbon::now()->addDay();
+        $timestamp = $datetime->getTimestamp();
+
+        return [
+            'DateTimeInterface' => [$datetime, $datetime],
+            'timestamp' => [$timestamp, $timestamp],
+        ];
+    }
+
+    #[DataProvider('retryUntilDataProvider')]
+    public function testRetryUntil(mixed $datetime, mixed $expected): void
+    {
+        $job = new FakeJob();
+        $result = $job->retryUntil($datetime);
+
+        $this->assertSame($job->retryUntil, $expected);
+        $this->assertSame($result, $job);
+    }
+
+    public function testRetryWithDelayReturnsSelfForFluentInterface(): void
+    {
+        $job = new FakeJob();
+        $result = $job->retryWithDelay(60);
+
+        $this->assertSame($job, $result);
+    }
+
+    public function testRetryUntilReturnsSelfForFluentInterface(): void
+    {
+        $job = new FakeJob();
+        $result = $job->retryUntil(Carbon::now());
+
+        $this->assertSame($job, $result);
+    }
+
+    public function testRetryWithDelayAndRetryUntilCanBeChained(): void
+    {
+        $job = new FakeJob();
+        $datetime = Carbon::now()->addDay();
+        $delays = [10, 30, 60];
+
+        $result = $job->retryWithDelay($delays)->retryUntil($datetime);
+
+        $this->assertSame($job->backoff, $delays);
+        $this->assertSame($job->retryUntil, $datetime);
+        $this->assertSame($result, $job);
+    }
+
+    public function testRetryWithDelayCanBeChainedWithOtherMethods(): void
+    {
+        $job = new FakeJob();
+
+        $result = $job->retryWithDelay(60)
+            ->onQueue('high')
+            ->onConnection('redis');
+
+        $this->assertSame($job->backoff, 60);
+        $this->assertSame($job->queue, 'high');
+        $this->assertSame($job->connection, 'redis');
+        $this->assertSame($result, $job);
+    }
+
+    public function testRetryUntilCanBeChainedWithOtherMethods(): void
+    {
+        $job = new FakeJob();
+        $datetime = Carbon::now()->addDay();
+
+        $result = $job->retryUntil($datetime)
+            ->onQueue('high')
+            ->delay(30);
+
+        $this->assertSame($job->retryUntil, $datetime);
+        $this->assertSame($job->queue, 'high');
+        $this->assertSame($job->delay, 30);
+        $this->assertSame($result, $job);
+    }
+
+    public function testRetryWithDelayPropertyIsUsedInQueuePayload(): void
+    {
+        $job = new FakeJob();
+        $job->retryWithDelay([10, 30, 60]);
+
+        $queue = new SyncQueue(new Container);
+        $queue->setContainer(new Container);
+
+        $reflection = new \ReflectionClass($queue);
+        $method = $reflection->getMethod('getJobBackoff');
+        $method->setAccessible(true);
+
+        $backoff = $method->invoke($queue, $job);
+
+        $this->assertSame('10,30,60', $backoff);
+    }
+
+    public function testRetryWithDelayWithSingleIntegerIsUsedInQueuePayload(): void
+    {
+        $job = new FakeJob();
+        $job->retryWithDelay(60);
+
+        $queue = new SyncQueue(new Container);
+        $queue->setContainer(new Container);
+
+        $reflection = new \ReflectionClass($queue);
+        $method = $reflection->getMethod('getJobBackoff');
+        $method->setAccessible(true);
+
+        $backoff = $method->invoke($queue, $job);
+
+        $this->assertSame('60', $backoff);
+    }
+
+    public function testRetryUntilPropertyIsUsedInQueuePayload(): void
+    {
+        $job = new FakeJob();
+        $datetime = Carbon::now()->addDay();
+        $job->retryUntil($datetime);
+
+        $queue = new SyncQueue(new Container);
+        $queue->setContainer(new Container);
+
+        $reflection = new \ReflectionClass($queue);
+        $method = $reflection->getMethod('getJobExpiration');
+        $method->setAccessible(true);
+
+        $expiration = $method->invoke($queue, $job);
+
+        $this->assertSame($datetime->getTimestamp(), $expiration);
+    }
+
+    public function testRetryUntilWithTimestampIsUsedInQueuePayload(): void
+    {
+        $job = new FakeJob();
+        $timestamp = Carbon::now()->addDay()->getTimestamp();
+        $job->retryUntil($timestamp);
+
+        $queue = new SyncQueue(new Container);
+        $queue->setContainer(new Container);
+
+        $reflection = new \ReflectionClass($queue);
+        $method = $reflection->getMethod('getJobExpiration');
+        $method->setAccessible(true);
+
+        $expiration = $method->invoke($queue, $job);
+
+        $this->assertSame($timestamp, $expiration);
+    }
+
+    public function testRetryWithDelayCanBeOverwritten(): void
+    {
+        $job = new FakeJob();
+        $job->retryWithDelay(60);
+        $job->retryWithDelay([10, 30]);
+
+        $this->assertSame($job->backoff, [10, 30]);
+    }
+
+    public function testRetryUntilCanBeOverwritten(): void
+    {
+        $job = new FakeJob();
+        $firstDatetime = Carbon::now()->addDay();
+        $secondDatetime = Carbon::now()->addDays(2);
+
+        $job->retryUntil($firstDatetime);
+        $job->retryUntil($secondDatetime);
+
+        $this->assertSame($job->retryUntil, $secondDatetime);
+    }
 }
 
 class FakeJob