feat: add isPast() and isFuture() time convenience methods

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
     // --------------------------------------------------------------------

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');

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() <api_response_trait_paginate>` for details.
 - **Time:** added methods ``Time::addCalendarMonths()`` and ``Time::subCalendarMonths()``
+- **Time:** Added ``Time::isPast()`` and ``Time::isFuture()`` convenience methods. See :ref:`isPast <time-comparing-two-times-isPast>` and :ref:`isFuture <time-comparing-two-times-isFuture>` for details.
 
 Commands
 ========

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

user_guide_src/source/libraries/time/043.php

@@ -0,0 +1,6 @@
+<?php
+
+use CodeIgniter\I18n\Time;
+
+$time = Time::parse('yesterday');
+echo $time->isPast(); // true

user_guide_src/source/libraries/time/044.php

@@ -0,0 +1,6 @@
+<?php
+
+use CodeIgniter\I18n\Time;
+
+$time = Time::parse('tomorrow');
+echo $time->isFuture(); // true