feat: add Time::addCalendarMonths() and Time::subCalendarMonths() methods (#9528)

* feat: [I18n\Time] addCalendarMonths()

* Remove return type

* fix addCalendarMonths() return type

* make addCalendarMonths() bi-directional and add subCalendarMonths()

* update userguide and changelog

* add tests for addCalendarMonths() and subCalendarMonths()

* user guide: functions -> methods

Co-authored-by: John Paul E. Balandan, CPA <[email protected]>

* revert change for TimeTrait::setTimeNow()

* Update TimeTrait.php

revert change to TimeTrait::setTimeNow()

* update user guide

* Update user_guide_src/source/libraries/time.rst

Co-authored-by: Michal Sniatala <[email protected]>

---------

Co-authored-by: John Paul E. Balandan, CPA <[email protected]>
Co-authored-by: Michal Sniatala <[email protected]>

Author: 3 people

system/I18n/TimeTrait.php

@@ -749,6 +749,39 @@ public function addMonths(int $months)
         return $time->add(DateInterval::createFromDateString("{$months} months"));
     }
 
+    /**
+     * Returns a new Time instance with $months calendar months added to the time.
+     */
+    public function addCalendarMonths(int $months): static
+    {
+        $time = clone $this;
+
+        $year  = (int) $time->getYear();
+        $month = (int) $time->getMonth();
+        $day   = (int) $time->getDay();
+
+        // Adjust total months since year 0
+        $totalMonths = ($year * 12 + $month - 1) + $months;
+
+        // Recalculate year and month
+        $newYear  = intdiv($totalMonths, 12);
+        $newMonth = $totalMonths % 12 + 1;
+
+        // Get last day of new month
+        $lastDayOfMonth = cal_days_in_month(CAL_GREGORIAN, $newMonth, $newYear);
+        $correctedDay   = min($day, $lastDayOfMonth);
+
+        return static::create($newYear, $newMonth, $correctedDay, (int) $this->getHour(), (int) $this->getMinute(), (int) $this->getSecond(), $this->getTimezone(), $this->locale);
+    }
+
+    /**
+     * Returns a new Time instance with $months calendar months subtracted from the time
+     */
+    public function subCalendarMonths(int $months): static
+    {
+        return $this->addCalendarMonths(-$months);
+    }
+
     /**
      * Returns a new Time instance with $years added to the time.
      *

tests/system/I18n/TimeTest.php

@@ -812,6 +812,22 @@ public function testCanAddMonthsOverYearBoundary(): void
         $this->assertSame('2018-02-10 13:20:33', $newTime->toDateTimeString());
     }
 
+    public function testCanAddCalendarMonths(): void
+    {
+        $time    = Time::parse('January 31, 2017 13:20:33', 'America/Chicago');
+        $newTime = $time->addCalendarMonths(1);
+        $this->assertSame('2017-01-31 13:20:33', $time->toDateTimeString());
+        $this->assertSame('2017-02-28 13:20:33', $newTime->toDateTimeString());
+    }
+
+    public function testCanAddCalendarMonthsOverYearBoundary(): void
+    {
+        $time    = Time::parse('January 31, 2017 13:20:33', 'America/Chicago');
+        $newTime = $time->addCalendarMonths(13);
+        $this->assertSame('2017-01-31 13:20:33', $time->toDateTimeString());
+        $this->assertSame('2018-02-28 13:20:33', $newTime->toDateTimeString());
+    }
+
     public function testCanAddYears(): void
     {
         $time    = Time::parse('January 10, 2017 13:20:33', 'America/Chicago');
@@ -860,6 +876,22 @@ public function testCanSubtractMonths(): void
         $this->assertSame('2016-10-10 13:20:33', $newTime->toDateTimeString());
     }
 
+    public function testCanSubtractCalendarMonths(): void
+    {
+        $time    = Time::parse('March 31, 2017 13:20:33', 'America/Chicago');
+        $newTime = $time->subCalendarMonths(1);
+        $this->assertSame('2017-03-31 13:20:33', $time->toDateTimeString());
+        $this->assertSame('2017-02-28 13:20:33', $newTime->toDateTimeString());
+    }
+
+    public function testCanSubtractCalendarMonthsOverYearBoundary(): void
+    {
+        $time    = Time::parse('March 31, 2017 13:20:33', 'America/Chicago');
+        $newTime = $time->subCalendarMonths(13);
+        $this->assertSame('2017-03-31 13:20:33', $time->toDateTimeString());
+        $this->assertSame('2016-02-29 13:20:33', $newTime->toDateTimeString());
+    }
+
     public function testCanSubtractYears(): void
     {
         $time    = Time::parse('January 10, 2017 13:20:33', 'America/Chicago');

user_guide_src/source/changelogs/v4.7.0.rst

@@ -33,6 +33,11 @@ Method Signature Changes
 Enhancements
 ************
 
+Libraries
+=========
+
+- **Time:** added methods ``Time::addCalendarMonths()`` and ``Time::subCalendarMonths()``
+
 Commands
 ========
 

user_guide_src/source/libraries/time.rst

@@ -325,6 +325,24 @@ modify the existing Time instance, but will return a new instance.
 
 .. literalinclude:: time/031.php
 
+addCalendarMonths() / subCalendarMonths()
+-----------------------------------------
+
+Modifies the current Time by adding or subtracting whole calendar months. These methods can be useful if you 
+require no calendar months are skipped in recurring dates. Refer to the table below for a comparison between 
+``addMonths()`` and ``addCalendarMonths()`` for an initial date of ``2025-01-31``.
+
+======= =========== =================== 
+$months addMonths() addCalendarMonths()
+======= =========== ===================
+1       2025-03-03  2025-02-28          
+2       2025-03-31  2025-03-31          
+3       2025-05-01  2025-04-30       
+4       2025-05-31  2025-05-31
+5       2025-07-01  2025-06-30
+6       2025-07-31  2025-07-31
+======= =========== ===================
+
 Comparing Two Times
 ===================
 

user_guide_src/source/libraries/time/031.php

@@ -5,11 +5,13 @@
 $time = $time->addHours(12);
 $time = $time->addDays(21);
 $time = $time->addMonths(14);
+$time = $time->addCalendarMonths(2);
 $time = $time->addYears(5);
 
 $time = $time->subSeconds(23);
 $time = $time->subMinutes(15);
 $time = $time->subHours(12);
 $time = $time->subDays(21);
 $time = $time->subMonths(14);
+$time = $time->subCalendarMonths(2);
 $time = $time->subYears(5);