Add ChronosPeriod which returns Chronos instances from DatePeriod

phpstan.neon

@@ -13,3 +13,7 @@ parameters:
 			message: "#^Call to an undefined static method DateTimeImmutable\\:\\:createFromTimestamp\\(\\)\\.$#"
 			count: 1
 			path: src/Chronos.php
+		-
+			message: "#with generic class DatePeriod but does not specify its types: TDate, TEnd, TRecurrences$#"
+			count: 1
+			path: src/ChronosPeriod.php

src/ChronosPeriod.php

@@ -0,0 +1,83 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
+ *
+ * Licensed under The MIT License
+ * Redistributions of files must retain the above copyright notice.
+ *
+ * @copyright     Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
+ * @link          https://cakephp.org CakePHP(tm) Project
+ * @license       https://www.opensource.org/licenses/mit-license.php MIT License
+ */
+
+namespace Cake\Chronos;
+
+use DatePeriod;
+use Iterator;
+
+/**
+ * DatePeriod wrapper that returns Chronos instances.
+ *
+ * @template TKey int
+ * @template TValue \Cake\Chronos\Chronos
+ * @template-implements \Iterator<int, \Cake\Chronos\Chronos>
+ */
+class ChronosPeriod implements Iterator
+{
+    /**
+     * @var \Iterator<int, \DateTimeInterface>
+     */
+    protected Iterator $iterator;
+
+    /**
+     * @param \DatePeriod $period
+     */
+    public function __construct(DatePeriod $period)
+    {
+        /** @var \Iterator<int, \DateTimeInterface> $iterator */
+        $iterator = $period->getIterator();
+        $this->iterator = $iterator;
+    }
+
+    /**
+     * @return \Cake\Chronos\Chronos
+     */
+    public function current(): Chronos
+    {
+        return new Chronos($this->iterator->current());
+    }
+
+    /**
+     * @return int
+     */
+    public function key(): int
+    {
+        return $this->iterator->key();
+    }
+
+    /**
+     * @return void
+     */
+    public function next(): void
+    {
+        $this->iterator->next();
+    }
+
+    /**
+     * @return void
+     */
+    public function rewind(): void
+    {
+        $this->iterator->rewind();
+    }
+
+    /**
+     * @return bool
+     */
+    public function valid(): bool
+    {
+        return $this->iterator->valid();
+    }
+}

tests/TestCase/ChronosPeriodTest.php

@@ -0,0 +1,38 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
+ *
+ * Licensed under The MIT License
+ * Redistributions of files must retain the above copyright notice.
+ *
+ * @copyright     Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
+ * @link          https://cakephp.org CakePHP(tm) Project
+ * @license       https://www.opensource.org/licenses/mit-license.php MIT License
+ */
+
+namespace Cake\Chronos\Test\TestCase;
+
+use Cake\Chronos\Chronos;
+use Cake\Chronos\ChronosPeriod;
+use DateInterval;
+use DatePeriod;
+use DateTime;
+
+class ChronosPeriodTest extends TestCase
+{
+    public function testChronosPeriod(): void
+    {
+        $period = new ChronosPeriod(new DatePeriod(new DateTime('2025-01-01 00:00:00'), new DateInterval('PT1H'), 3));
+        $output = [];
+        foreach ($period as $key => $value) {
+            $output[$key] = $value;
+        }
+        $this->assertCount(4, $output);
+        $this->assertInstanceOf(Chronos::class, $output[0]);
+        $this->assertSame('2025-01-01 00:00:00', $output[0]->format('Y-m-d H:i:s'));
+        $this->assertInstanceOf(Chronos::class, $output[1]);
+        $this->assertSame('2025-01-01 01:00:00', $output[1]->format('Y-m-d H:i:s'));
+    }
+}