Merge remote-tracking branch 'origin/3.x' into 3.next

Author: dereuromark

CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing to Chronos
+
+Thank you for your interest in contributing to Chronos! This document provides guidelines and instructions for contributing.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/chronos.git
+   cd chronos
+   ```
+3. Install dependencies:
+   ```bash
+   composer install
+   ```
+
+## Running Tests
+
+Run the test suite using PHPUnit:
+
+```bash
+composer test
+```
+
+Or directly:
+
+```bash
+vendor/bin/phpunit
+```
+
+## Code Style
+
+This project follows the [CakePHP coding standards](https://book.cakephp.org/5/en/contributing/cakephp-coding-conventions.html).
+
+Check for coding standard violations:
+
+```bash
+composer cs-check
+```
+
+Automatically fix coding standard violations:
+
+```bash
+composer cs-fix
+```
+
+## Static Analysis
+
+PHPStan is used for static analysis. First, install the tools:
+
+```bash
+composer stan-setup
+```
+
+Then run the analysis:
+
+```bash
+composer stan
+```
+
+## Running All Checks
+
+To run tests, coding standards, and static analysis together:
+
+```bash
+composer check
+```
+
+## Submitting Changes
+
+1. Create a new branch for your changes
+2. Make your changes and commit them with clear, descriptive messages
+3. Ensure all checks pass (`composer check`)
+4. Push to your fork and submit a pull request
+
+## Reporting Issues
+
+- Search existing issues before creating a new one
+- Include PHP version, Chronos version, and a minimal reproduction case
+- Use clear, descriptive titles
+
+## Documentation
+
+Documentation source files are located in the `docs/` directory. The documentation is published at [book.cakephp.org/chronos](https://book.cakephp.org/chronos/3/en/).

src/Chronos.php

@@ -692,9 +692,96 @@ public static function createFromFormat(
             throw new InvalidArgumentException($message);
         }
 
+        $testNow = static::getTestNow();
+        if ($testNow !== null) {
+            $dateTime = static::applyTestNowToMissingComponents($dateTime, $format, $testNow);
+        }
+
         return $dateTime;
     }
 
+    /**
+     * Apply testNow values to date/time components that weren't in the format string.
+     *
+     * @param static $dateTime The parsed datetime instance.
+     * @param string $format The format string used for parsing.
+     * @param \Cake\Chronos\Chronos $testNow The test now instance.
+     * @return static
+     */
+    protected static function applyTestNowToMissingComponents(
+        self $dateTime,
+        string $format,
+        Chronos $testNow,
+    ): static {
+        // Parse format string to find which characters are actual format specifiers (not escaped)
+        $formatChars = static::getFormatCharacters($format);
+
+        // Check which components are present in the format
+        $hasYear = (bool)array_intersect($formatChars, ['Y', 'y', 'o', 'X', 'x']);
+        $hasMonth = (bool)array_intersect($formatChars, ['m', 'n', 'M', 'F']);
+        $hasDay = (bool)array_intersect($formatChars, ['d', 'j', 'D', 'l', 'N', 'z', 'w', 'W', 'S']);
+        $hasHour = (bool)array_intersect($formatChars, ['H', 'G', 'h', 'g']);
+        $hasMinute = (bool)array_intersect($formatChars, ['i']);
+        $hasSecond = (bool)array_intersect($formatChars, ['s']);
+        $hasMicro = (bool)array_intersect($formatChars, ['u', 'v']);
+
+        // If the format includes '!' or '|', PHP resets unspecified components to Unix epoch or zero
+        // In that case, we should not override with testNow
+        $hasReset = in_array('!', $formatChars, true) || in_array('|', $formatChars, true);
+        if ($hasReset) {
+            return $dateTime;
+        }
+
+        // Replace missing components with testNow values
+        $year = $hasYear ? $dateTime->year : $testNow->year;
+        $month = $hasMonth ? $dateTime->month : $testNow->month;
+        $day = $hasDay ? $dateTime->day : $testNow->day;
+        $hour = $hasHour ? $dateTime->hour : $testNow->hour;
+        $minute = $hasMinute ? $dateTime->minute : $testNow->minute;
+        $second = $hasSecond ? $dateTime->second : $testNow->second;
+        $micro = $hasMicro ? $dateTime->micro : $testNow->micro;
+
+        // Only modify if something needs to change
+        if (
+            !$hasYear || !$hasMonth || !$hasDay ||
+            !$hasHour || !$hasMinute || !$hasSecond || !$hasMicro
+        ) {
+            return $dateTime
+                ->setDate($year, $month, $day)
+                ->setTime($hour, $minute, $second, $micro);
+        }
+
+        return $dateTime;
+    }
+
+    /**
+     * Extract format characters from a format string, handling escapes.
+     *
+     * @param string $format The format string.
+     * @return array<string> Array of format characters.
+     */
+    protected static function getFormatCharacters(string $format): array
+    {
+        $chars = [];
+        $length = strlen($format);
+        $i = 0;
+
+        while ($i < $length) {
+            $char = $format[$i];
+
+            // Backslash escapes the next character
+            if ($char === '\\' && $i + 1 < $length) {
+                $i += 2;
+                continue;
+            }
+
+            $chars[] = $char;
+            $i++;
+        }
+
+        return $chars;
+    }
+
     /**
      * Returns parse warnings and errors from the last ``createFromFormat()``
      * call.

src/ChronosDatePeriod.php

@@ -14,7 +14,9 @@
 
 namespace Cake\Chronos;
 
+use DateInterval;
 use DatePeriod;
+use InvalidArgumentException;
 use Iterator;
 
 /**
@@ -32,15 +34,39 @@ class ChronosDatePeriod implements Iterator
     protected Iterator $iterator;
 
     /**
-     * @param \DatePeriod $period
+     * @param \DatePeriod $period The DatePeriod to wrap.
+     * @throws \InvalidArgumentException If the period has a zero interval which would cause an infinite loop.
      */
     public function __construct(DatePeriod $period)
     {
+        if (static::isZeroInterval($period->getDateInterval())) {
+            throw new InvalidArgumentException(
+                'Cannot create a period with a zero interval. This would cause an infinite loop when iterating.',
+            );
+        }
+
         /** @var \Iterator<int, \DateTimeInterface> $iterator */
         $iterator = $period->getIterator();
         $this->iterator = $iterator;
     }
 
+    /**
+     * Check if a DateInterval is effectively zero.
+     *
+     * @param \DateInterval $interval The interval to check.
+     * @return bool True if the interval is zero.
+     */
+    protected static function isZeroInterval(DateInterval $interval): bool
+    {
+        return $interval->y === 0
+            && $interval->m === 0
+            && $interval->d === 0
+            && $interval->h === 0
+            && $interval->i === 0
+            && $interval->s === 0
+            && (int)($interval->f * 1_000_000) === 0;
+    }
+
     /**
      * @return \Cake\Chronos\ChronosDate
      */

src/ChronosPeriod.php

@@ -14,7 +14,9 @@
 
 namespace Cake\Chronos;
 
+use DateInterval;
 use DatePeriod;
+use InvalidArgumentException;
 use Iterator;
 
 /**
@@ -32,15 +34,39 @@ class ChronosPeriod implements Iterator
     protected Iterator $iterator;
 
     /**
-     * @param \DatePeriod $period
+     * @param \DatePeriod $period The DatePeriod to wrap.
+     * @throws \InvalidArgumentException If the period has a zero interval which would cause an infinite loop.
      */
     public function __construct(DatePeriod $period)
     {
+        if (static::isZeroInterval($period->getDateInterval())) {
+            throw new InvalidArgumentException(
+                'Cannot create a period with a zero interval. This would cause an infinite loop when iterating.',
+            );
+        }
+
         /** @var \Iterator<int, \DateTimeInterface> $iterator */
         $iterator = $period->getIterator();
         $this->iterator = $iterator;
     }
 
+    /**
+     * Check if a DateInterval is effectively zero.
+     *
+     * @param \DateInterval $interval The interval to check.
+     * @return bool True if the interval is zero.
+     */
+    protected static function isZeroInterval(DateInterval $interval): bool
+    {
+        return $interval->y === 0
+            && $interval->m === 0
+            && $interval->d === 0
+            && $interval->h === 0
+            && $interval->i === 0
+            && $interval->s === 0
+            && (int)($interval->f * 1_000_000) === 0;
+    }
+
     /**
      * @return \Cake\Chronos\Chronos
      */

tests/TestCase/ChronosDatePeriodTest.php

@@ -19,6 +19,7 @@
 use DateInterval;
 use DatePeriod;
 use DateTime;
+use InvalidArgumentException;
 
 class ChronosDatePeriodTest extends TestCase
 {
@@ -30,11 +31,37 @@ public function testChronosPeriod(): void
             $output[$key] = $value;
         }
         $this->assertCount(4, $output);
-        $this->assertInstanceOf(ChronosDAte::class, $output[0]);
+        $this->assertInstanceOf(ChronosDate::class, $output[0]);
         $this->assertSame('2025-01-01 00:00:00', $output[0]->format('Y-m-d H:i:s'));
         $this->assertInstanceOf(ChronosDate::class, $output[1]);
         $this->assertSame('2025-01-02 00:00:00', $output[1]->format('Y-m-d H:i:s'));
         $this->assertInstanceOf(ChronosDate::class, $output[3]);
         $this->assertSame('2025-01-04 00:00:00', $output[3]->format('Y-m-d H:i:s'));
     }
+
+    public function testZeroIntervalThrowsException(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Cannot create a period with a zero interval');
+
+        $period = new DatePeriod(
+            new DateTime('2025-01-01'),
+            new DateInterval('PT0S'),
+            new DateTime('2025-01-02'),
+        );
+        new ChronosDatePeriod($period);
+    }
+
+    public function testZeroIntervalAllZeroComponents(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        $interval = new DateInterval('P0D');
+        $period = new DatePeriod(
+            new DateTime('2025-01-01'),
+            $interval,
+            new DateTime('2025-01-02'),
+        );
+        new ChronosDatePeriod($period);
+    }
 }

tests/TestCase/ChronosPeriodTest.php

@@ -19,6 +19,7 @@
 use DateInterval;
 use DatePeriod;
 use DateTime;
+use InvalidArgumentException;
 
 class ChronosPeriodTest extends TestCase
 {
@@ -35,4 +36,30 @@ public function testChronosPeriod(): void
         $this->assertInstanceOf(Chronos::class, $output[1]);
         $this->assertSame('2025-01-01 01:00:00', $output[1]->format('Y-m-d H:i:s'));
     }
+
+    public function testZeroIntervalThrowsException(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Cannot create a period with a zero interval');
+
+        $period = new DatePeriod(
+            new DateTime('2025-01-01'),
+            new DateInterval('PT0S'),
+            new DateTime('2025-01-02'),
+        );
+        new ChronosPeriod($period);
+    }
+
+    public function testZeroIntervalAllZeroComponents(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        $interval = new DateInterval('P0D');
+        $period = new DatePeriod(
+            new DateTime('2025-01-01'),
+            $interval,
+            new DateTime('2025-01-02'),
+        );
+        new ChronosPeriod($period);
+    }
 }