diff --git a/system/I18n/TimeTrait.php b/system/I18n/TimeTrait.php index 2442f4b0c613..42cd1724b8c4 100644 --- a/system/I18n/TimeTrait.php +++ b/system/I18n/TimeTrait.php @@ -1028,6 +1028,26 @@ public function isAfter($testTime, ?string $timezone = null): bool return $ourTimestamp > $testTimestamp; } + /** + * Determines if the current instance's time is in the past. + * + * @throws Exception + */ + public function isPast(): bool + { + return $this->isBefore(static::now($this->timezone)); + } + + /** + * Determines if the current instance's time is in the future. + * + * @throws Exception + */ + public function isFuture(): bool + { + return $this->isAfter(static::now($this->timezone)); + } + // -------------------------------------------------------------------- // Differences // -------------------------------------------------------------------- diff --git a/tests/system/I18n/TimeTest.php b/tests/system/I18n/TimeTest.php index 4f76636ac7eb..9fb4b9226a85 100644 --- a/tests/system/I18n/TimeTest.php +++ b/tests/system/I18n/TimeTest.php @@ -1040,6 +1040,34 @@ public function testAfterWithMicroseconds(): void $this->assertFalse($time2->isAfter($time1)); } + public function testIsPast(): void + { + Time::setTestNow('2025-12-30 12:00:00', 'Asia/Tehran'); + + $past = Time::parse('2025-12-30 11:59:59', 'Asia/Tehran'); + $this->assertTrue($past->isPast()); + + $future = Time::parse('2025-12-30 12:00:01', 'Asia/Tehran'); + $this->assertFalse($future->isPast()); + + $now = Time::now('Asia/Tehran'); + $this->assertFalse($now->isPast()); + } + + public function testIsFuture(): void + { + Time::setTestNow('2025-12-30 12:00:00', 'Asia/Tehran'); + + $future = Time::parse('2025-12-30 12:00:01', 'Asia/Tehran'); + $this->assertTrue($future->isFuture()); + + $past = Time::parse('2025-12-30 11:59:59', 'Asia/Tehran'); + $this->assertFalse($past->isFuture()); + + $now = Time::now('Asia/Tehran'); + $this->assertFalse($now->isFuture()); + } + public function testHumanizeYearsSingle(): void { Time::setTestNow('March 10, 2017', 'America/Chicago'); diff --git a/user_guide_src/source/changelogs/v4.7.0.rst b/user_guide_src/source/changelogs/v4.7.0.rst index 2355e9a9f420..6000ed97cfc3 100644 --- a/user_guide_src/source/changelogs/v4.7.0.rst +++ b/user_guide_src/source/changelogs/v4.7.0.rst @@ -181,6 +181,7 @@ Libraries - **Image:** Added ``ImageMagickHandler::clearMetadata()`` method to remove image metadata for privacy protection. - **ResponseTrait:** Added ``paginate``` method to simplify paginated API responses. See :ref:`ResponseTrait::paginate() ` for details. - **Time:** added methods ``Time::addCalendarMonths()`` and ``Time::subCalendarMonths()`` +- **Time:** Added ``Time::isPast()`` and ``Time::isFuture()`` convenience methods. See :ref:`isPast ` and :ref:`isFuture ` for details. Commands ======== diff --git a/user_guide_src/source/libraries/time.rst b/user_guide_src/source/libraries/time.rst index c3ddb3c16d39..53b869b1b12a 100644 --- a/user_guide_src/source/libraries/time.rst +++ b/user_guide_src/source/libraries/time.rst @@ -393,6 +393,30 @@ Works exactly the same as ``isBefore()`` except checks if the time is after the .. literalinclude:: time/037.php +.. _time-comparing-two-times-isPast: + +isPast() +-------- + +.. versionadded:: 4.7.0 + +Determines if the current instance's time is in the past, relative to "now". +It returns a boolean true/false:: + +.. literalinclude:: time/043.php + +.. _time-comparing-two-times-isFuture: + +isFuture() +---------- + +.. versionadded:: 4.7.0 + +Determines if the current instance's time is in the future, relative to "now". +It returns a boolean true/false:: + +.. literalinclude:: time/044.php + .. _time-viewing-differences: Viewing Differences diff --git a/user_guide_src/source/libraries/time/043.php b/user_guide_src/source/libraries/time/043.php new file mode 100644 index 000000000000..b256fff3ddce --- /dev/null +++ b/user_guide_src/source/libraries/time/043.php @@ -0,0 +1,6 @@ +isPast(); // true diff --git a/user_guide_src/source/libraries/time/044.php b/user_guide_src/source/libraries/time/044.php new file mode 100644 index 000000000000..d8cc511065c7 --- /dev/null +++ b/user_guide_src/source/libraries/time/044.php @@ -0,0 +1,6 @@ +isFuture(); // true