[12.x] Allow down command --retry option to accept datetime values (#58509)

* Enhance `down` command to support datetime for Retry-After header/option

* formatting

* formatting

---------

Co-authored-by: Taylor Otwell <taylor@laravel.com>

Author: alies-dev

src/Illuminate/Foundation/Console/DownCommand.php

@@ -3,10 +3,12 @@
 namespace Illuminate\Foundation\Console;
 
 use App\Http\Middleware\PreventRequestsDuringMaintenance;
+use DateTimeInterface;
 use Exception;
 use Illuminate\Console\Command;
 use Illuminate\Foundation\Events\MaintenanceModeEnabled;
 use Illuminate\Foundation\Exceptions\RegisterErrorViewPaths;
+use Illuminate\Support\Carbon;
 use Illuminate\Support\Str;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Throwable;
@@ -21,7 +23,7 @@ class DownCommand extends Command
      */
     protected $signature = 'down {--redirect= : The path that users should be redirected to}
                                  {--render= : The view that should be prerendered for display during maintenance mode}
-                                 {--retry= : The number of seconds after which the request may be retried}
+                                 {--retry= : The number of seconds or the datetime after which the request may be retried}
                                  {--refresh= : The number of seconds after which the browser may refresh}
                                  {--secret= : The secret phrase that may be used to bypass maintenance mode}
                                  {--with-secret : Generate a random secret phrase that may be used to bypass maintenance mode}
@@ -135,15 +137,29 @@ protected function prerenderView()
     }
 
     /**
-     * Get the number of seconds the client should wait before retrying their request.
+     * Get the number of seconds or date / time the client should wait before retrying their request.
      *
-     * @return int|null
+     * @return int|string|null
      */
     protected function getRetryTime()
     {
         $retry = $this->option('retry');
 
-        return is_numeric($retry) && $retry > 0 ? (int) $retry : null;
+        if (is_numeric($retry) && $retry > 0) {
+            return (int) $retry;
+        }
+
+        if (is_string($retry) && ! empty($retry)) {
+            try {
+                $date = Carbon::parse($retry);
+
+                return $date->format(DateTimeInterface::RFC7231);
+            } catch (Exception) {
+                return null;
+            }
+        }
+
+        return null;
     }
 
     /**

tests/Integration/Foundation/MaintenanceModeTest.php

@@ -2,6 +2,7 @@
 
 namespace Illuminate\Tests\Integration\Foundation;
 
+use DateTimeInterface;
 use Illuminate\Foundation\Console\DownCommand;
 use Illuminate\Foundation\Console\UpCommand;
 use Illuminate\Foundation\Events\MaintenanceModeDisabled;
@@ -12,6 +13,7 @@
 use Illuminate\Support\Facades\Event;
 use Illuminate\Support\Facades\Route;
 use Orchestra\Testbench\TestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
 use Symfony\Component\HttpFoundation\Cookie;
 
 class MaintenanceModeTest extends TestCase
@@ -192,4 +194,62 @@ public function testDispatchEventWhenMaintenanceModeIsDisabled()
         $this->artisan(UpCommand::class);
         Event::assertDispatched(MaintenanceModeDisabled::class);
     }
+
+    #[DataProvider('retryAfterDatetimeProvider')]
+    public function testMaintenanceModeRetryCanAcceptDatetime(string $datetime): void
+    {
+        $this->artisan(DownCommand::class, ['--retry' => $datetime]);
+
+        $data = json_decode(file_get_contents(storage_path('framework/down')), true);
+
+        $expectedDate = Carbon::parse($datetime)->format(DateTimeInterface::RFC7231);
+        $this->assertSame($expectedDate, $data['retry']);
+    }
+
+    public static function retryAfterDatetimeProvider(): array
+    {
+        return [
+            'ISO 8601 format' => [date('Y-m-d H:i:s', strtotime('+1 week'))],
+            'natural language' => ['tomorrow 14:00'],
+            'relative time' => ['+2 hours'],
+        ];
+    }
+
+    public function testMaintenanceModeRetryWithHttpDateHeader(): void
+    {
+        $retryDate = Carbon::now()->addWeek();
+        $expectedHeader = $retryDate->format(DateTimeInterface::RFC7231);
+
+        file_put_contents(storage_path('framework/down'), json_encode([
+            'retry' => $expectedHeader,
+        ]));
+
+        Route::get('/foo', fn () => 'Hello World')->middleware(PreventRequestsDuringMaintenance::class);
+
+        $response = $this->get('/foo');
+
+        $response->assertStatus(503);
+        $response->assertHeader('Retry-After', $expectedHeader);
+    }
+
+    public function testMaintenanceModeRetryWithInvalidDatetimeReturnsNull(): void
+    {
+        $this->artisan(DownCommand::class, ['--retry' => 'not-a-valid-date']);
+
+        $data = json_decode(file_get_contents(storage_path('framework/down')), true);
+
+        $this->assertNull($data['retry']);
+    }
+
+    public function testMaintenanceModeRetryWithAtTimestampNotation(): void
+    {
+        $futureTimestamp = time() + 3600;
+
+        $this->artisan(DownCommand::class, ['--retry' => '@'.$futureTimestamp]);
+
+        $data = json_decode(file_get_contents(storage_path('framework/down')), true);
+
+        $expectedDate = Carbon::createFromTimestamp($futureTimestamp)->format(DateTimeInterface::RFC7231);
+        $this->assertSame($expectedDate, $data['retry']);
+    }
 }