Chronos fluent setters set the incorrect month under some scenarios.

[josep11]

I have been trying to understand what is the issue why it is setting the wrong month when using the ->month() fluent setter.
I outline how to reproduce the issue, which can be seen at the composeDatetime method.
At the bottom of the bug, you can see a workaround that does work, for the provided scenarios.

Function Body (and dependencies):

class Service
{
    private function composeDatetime(?Chronos $eventDatetime, Chronos $eventSeriesDay): Chronos
    {
        if (null === $eventDatetime) {
            throw new LogicException();
        }

        $year = $eventSeriesDay->year;
        $month = $eventSeriesDay->month;
        $day = $eventSeriesDay->day;

// This does not work
        return Chronos::create()
            ->year($year)
            ->month($month)
            ->day($day)
            ->hour($eventDatetime->hour)
            ->minute($eventDatetime->minute)
            ->second($eventDatetime->second);
    }

    public function fixStartAndEndDatesInRequest(
        EventRequest $eventRequest,
        Chronos $eventSeriesDay,
    ): void
    {
        $datetimeStart = $eventRequest->getDatetimeStart();
        $datetimeEnd = $eventRequest->getDatetimeEnd();

        $eventDatetimeStart = $this->composeDatetime($datetimeStart, $eventSeriesDay);
        $eventDatetimeEnd = $this->composeDatetime($datetimeEnd, $eventSeriesDay);

        $eventRequest->setDatetimeStart($eventDatetimeStart);
        $eventRequest->setDatetimeEnd($eventDatetimeEnd);
    }
}

// dependencies for reproduction
class EventRequest {
    private ?Chronos $datetimeStart = null;
    private ?Chronos $datetimeEnd = null;
    
    public function setDatetimeStart(?Chronos $datetimeStart): self {
        $this->datetimeStart = $datetimeStart;
        
        return $this;
    }
    
    public function setDatetimeEnd(?Chronos $datetimeEnd): self {
        $this->datetimeEnd = $datetimeEnd;

        return $this;
    }
    
    public function getDatetimeStart(): ?Chronos {
        return $this->datetimeStart;
    }
    
    public function getDatetimeEnd(): ?Chronos {
        return $this->datetimeEnd;
    }
}

Unit Test:

class ChronosTest extends \PHPUnit\Framework\TestCase
{

    #[DataProvider('dataProviderForFixStartAndEndDatesInRequestDto')]
    public function testFixStartAndEndDatesInRequestDto(array $provider): void
    {
        $datetimeStart = $provider['datetimeStart'];
        $datetimeEnd = $provider['datetimeEnd'];
        $eventSeriesDay = $provider['eventSeriesDay'];

        $expectedDateTimeStart = $provider['expectedDateTimeStart'];
        $expectedDateTimeEnd = $provider['expectedDateTimeEnd'];

        $requestDto = new EventRequest()
            ->setDatetimeStart($datetimeStart)
            ->setDatetimeEnd($datetimeEnd);

        $this->service->fixStartAndEndDatesInRequest($requestDto, $eventSeriesDay);

        // Assert the date parts are updated correctly
        $this->assertEquals(
            $expectedDateTimeStart,
            $requestDto->getDatetimeStart()->toNative(),
            'Start date was not updated correctly'
        );
        $this->assertEquals(
            $expectedDateTimeEnd,
            $requestDto->getDatetimeEnd()->toNative(),
            'End date was not updated correctly'
        );

        // Assert the times are ok
        $this->assertEquals(
            $datetimeStart->toTimeString(),
            $requestDto->getDatetimeStart()->toTimeString(),
            'Start time was not updated correctly'
        );
        $this->assertEquals(
            $datetimeEnd->toTimeString(),
            $requestDto->getDatetimeEnd()->toTimeString(),
            'End time was not updated correctly'
        );
    }

    public static function dataProviderForFixStartAndEndDatesInRequestDto(): array
    {
        $datetimeStartOct = new Chronos('2025-10-27 09:00:00');
        $datetimeEndOct = new Chronos('2025-10-27 11:00:00');

        $datetimeStartJan = new Chronos('2026-01-29 09:00:00.000000');
        $datetimeEndJan = new Chronos('2026-01-29 10:00:00.000000');

        $datetimeStartOct2 = new Chronos('2025-10-29 09:00:00');
        $datetimeEndOct2 = new Chronos('2025-10-29 11:00:00');

        return [
            'Event start date is on October, series day is in November' => [
                [
                    'datetimeStart' => $datetimeStartOct,
                    'datetimeEnd' => $datetimeEndOct,
                    'eventSeriesDay' => new Chronos('2025-11-01 00:00:00'),

                    'expectedDateTimeStart' => $datetimeStartOct->setDate(2025, 11, 1)->toNative(),
                    'expectedDateTimeEnd' => $datetimeEndOct->setDate(2025, 11, 1)->toNative(),
                ],
            ],
            'Event start date is on October, series day is in February' => [
                [
                    'datetimeStart' => $datetimeStartOct,
                    'datetimeEnd' => $datetimeEndOct,
                    'eventSeriesDay' => new Chronos('2026-02-04 00:00:00'),

                    'expectedDateTimeStart' => $datetimeStartOct->setDate(2026, 2, 4)->toNative(),
                    'expectedDateTimeEnd' => $datetimeEndOct->setDate(2026, 2, 4)->toNative(),
                ],
            ],
            'Event start date is on October, series day is in February (2)' => [
                [
                    'datetimeStart' => $datetimeStartOct2,
                    'datetimeEnd' => $datetimeEndOct2,
                    'eventSeriesDay' => new Chronos('2026-02-04 00:00:00'),

                    'expectedDateTimeStart' => $datetimeStartOct2->setDate(2026, 2, 4)->toNative(),
                    'expectedDateTimeEnd' => $datetimeEndOct2->setDate(2026, 2, 4)->toNative(),
                ],
            ],
            'Event start date is on January, series day is in February' => [
                [
                    'datetimeStart' => $datetimeStartJan,
                    'datetimeEnd' => $datetimeEndJan,
                    'eventSeriesDay' => new Chronos('2026-02-04 00:00:00'),

                    'expectedDateTimeStart' => $datetimeStartJan->setDate(2026, 2, 4)->toNative(),
                    'expectedDateTimeEnd' => $datetimeEndJan->setDate(2026, 2, 4)->toNative(),
                ],
            ],
        ];
    }
}

Now, if using the Chronos::create with parameters, straight away, it does work.

private function composeDatetime(?Chronos $eventDatetime, Chronos $eventSeriesDay): Chronos
    {
        if (null === $eventDatetime) {
            throw new LogicException();
        }

        $year = $eventSeriesDay->year;
        $month = $eventSeriesDay->month;
        $day = $eventSeriesDay->day;

// works
        return Chronos::create(
            $year,
            $month,
            $day,
            $eventDatetime->hour,
            $eventDatetime->minute,
            $eventDatetime->second,
        );
    }

[ajibarra]

Hello, I think the problem is not in Chronos itself but caused by not being possible to represent specific days in a month (i.e Nov 31, Feb 30, etc)

The thing is that Chronos::create() (with no parameters) uses today's date.

Let's say today is October 31. When your code runs, this happens:

Chronos::create()

It creates a date for today.

Value is: 2025-10-31 (using today as example)

->year(2026)

It changes the year.

Value is now: 2026-10-31

->month(2)

This is the problem. It tries to set the month to February.

It tries to make 2026-02-31.

This date is impossible. Chronos "fixes" it and moves the date to March (e.g. 2026-03-03, because Feb has 28 days).

->day(4)

It changes the day.

Final value is: 2026-03-04

This is why you get March, not February.

Your other code (the fix) works: Chronos::create(2026, 2, 4, ...)

This version does not use today's date. It builds the correct date 2026-02-04 all at once.

I tried setting day to 27th in Chronos::L573 $now = static::now()->day(27); to fake that today is 27th and tests passed. If a leave the 31st all of them fails. But it also should work if you set day before setting month:

return Chronos::create()
            ->year($year)
            ->day($day)
            ->month($month)
            ->hour($eventDatetime->hour)
            ->minute($eventDatetime->minute)
            ->second($eventDatetime->second);

[josep11]

Hello, I think the problem is not in Chronos itself but caused by not being possible to represent specific days in a month (i.e Nov 31, Feb 30, etc)

The thing is that Chronos::create() (with no parameters) uses today's date.

Let's say today is October 31. When your code runs, this happens:

Chronos::create()

It creates a date for today.

Value is: 2025-10-31 (using today as example)

->year(2026)

It changes the year.

Value is now: 2026-10-31

->month(2)

This is the problem. It tries to set the month to February.

It tries to make 2026-02-31.

This date is impossible. Chronos "fixes" it and moves the date to March (e.g. 2026-03-03, because Feb has 28 days).

->day(4)

It changes the day.

Final value is: 2026-03-04

This is why you get March, not February.

Your other code (the fix) works: Chronos::create(2026, 2, 4, ...)

This version does not use today's date. It builds the correct date 2026-02-04 all at once.

I tried setting day to 27th in Chronos::L573 $now = static::now()->day(27); to fake that today is 27th and tests passed. If a leave the 31st all of them fails. But it also should work if you set day before setting month:

return Chronos::create()
            ->year($year)
            ->day($day)
            ->month($month)
            ->hour($eventDatetime->hour)
            ->minute($eventDatetime->minute)
            ->second($eventDatetime->second);

Ah, de acuerdo. Tiene sentido. Gracias.

En cualquier caso, yo creo que sería mejor lanzar una excepción, ya que este comportamiento puede traer consecuencias inesperadas. Pero está bien.

Saludos

[dereuromark]

Yeah, this is expected behavior, though I understand it's counterintuitive. The issue is that when you chain setters like ->year(2026)->month(2)->day(4) starting from Chronos::create() (which defaults to today), each setter
operates on the result of the previous operation.

If today is October 31st:

1. Chronos::create() → 2025-10-31
2. ->year(2026) → 2026-10-31
3. ->month(2) → attempts 2026-02-31, which is invalid, so PHP's DateTime rolls forward to 2026-03-03
4. ->day(4) → 2026-03-04 (March, not February)

Solutions:

1. Use atomic creation (recommended):
   Chronos::create(2026, 2, 4, ...)
2. Set day first when chaining:
   Chronos::create()->year(2026)->day(4)->month(2)
3. This avoids the overflow since you set day to 4 before changing the month.
4. Use createFromDate():
   Chronos::createFromDate(2026, 2, 4)

[josep11]

Yep, sure, last day I fixed it with atomic creation. It's the best way.

However, I wanted to raise the consideration of counterintuitive-ness to see if the team wants to change it.