Add expiresAt(), registeredAt(), updatedAt(), and expiresInDays() methods to Dates

Author: boutetnico

src/Responses/Dates.php

@@ -23,4 +23,46 @@ public static function fromArray(array $data): self
             updated: $data['updated'] ?? null,
         );
     }
+
+    /** Parse the registered date into a DateTimeImmutable, or null. */
+    public function registeredAt(): ?\DateTimeImmutable
+    {
+        return self::parse($this->registered);
+    }
+
+    /** Parse the expiry date into a DateTimeImmutable, or null. */
+    public function expiresAt(): ?\DateTimeImmutable
+    {
+        return self::parse($this->expires);
+    }
+
+    /** Parse the updated date into a DateTimeImmutable, or null. */
+    public function updatedAt(): ?\DateTimeImmutable
+    {
+        return self::parse($this->updated);
+    }
+
+    /** Days until expiration, or null if no expiry date is available. */
+    public function expiresInDays(): ?int
+    {
+        $dt = $this->expiresAt();
+        if ($dt === null) {
+            return null;
+        }
+
+        return (int) (new \DateTimeImmutable('now', new \DateTimeZone('UTC')))->diff($dt)->format('%r%a');
+    }
+
+    private static function parse(?string $value): ?\DateTimeImmutable
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        try {
+            return new \DateTimeImmutable($value);
+        } catch (\Exception) {
+            return null;
+        }
+    }
 }

tests/ResponsesTest.php

@@ -173,6 +173,37 @@
         ->and($entities->abuse->name)->toBe('Abuse');
 });
 
+it('parses dates into DateTimeImmutable', function () {
+    $dates = Dates::fromArray([
+        'registered' => '2020-01-01T00:00:00Z',
+        'expires' => '2028-09-14T04:00:00Z',
+        'updated' => '2024-02-20T10:16:08Z',
+    ]);
+
+    expect($dates->registeredAt())->toBeInstanceOf(\DateTimeImmutable::class)
+        ->and($dates->registeredAt()->format('Y'))->toBe('2020')
+        ->and($dates->expiresAt())->toBeInstanceOf(\DateTimeImmutable::class)
+        ->and($dates->updatedAt())->toBeInstanceOf(\DateTimeImmutable::class)
+        ->and($dates->expiresInDays())->toBeGreaterThan(0);
+});
+
+it('returns null for missing dates', function () {
+    $dates = Dates::fromArray([]);
+
+    expect($dates->registeredAt())->toBeNull()
+        ->and($dates->expiresAt())->toBeNull()
+        ->and($dates->updatedAt())->toBeNull()
+        ->and($dates->expiresInDays())->toBeNull();
+});
+
+it('returns null for invalid date strings', function () {
+    $dates = Dates::fromArray(['registered' => 'not-a-date', 'expires' => 'garbage']);
+
+    expect($dates->registeredAt())->toBeNull()
+        ->and($dates->expiresAt())->toBeNull()
+        ->and($dates->expiresInDays())->toBeNull();
+});
+
 it('handles empty arrays gracefully', function () {
     $ip = IpAddresses::fromArray([]);
     expect($ip->v4)->toBe([])