Skip to content

feat: add Time between(), min(), and max() methods #10149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
michalsn wants to merge 5 commits into
base: 4.8
Choose a base branch
from
Open

feat: add Time between(), min(), and max() methods #10149

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
58c3584
feat: add Time between(), min(), and max() methods
michalsn Apr 30, 2026
b3d10cf
apply code review suggestion
michalsn May 1, 2026
a37bbd6
early return
michalsn May 1, 2026
326f9e0
apply code suggestions
michalsn May 2, 2026
a34d839
revert getUTCObject() changes and add test
michalsn May 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 90 additions & 28 deletions system/I18n/TimeTrait.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@
use CodeIgniter\I18n\Exceptions\I18nException;
use DateInterval;
use DateTime;
use DateTimeImmutable;
use DateTimeInterface;
use DateTimeZone;
use Exception;
Expand Down Expand Up @@ -966,14 +965,7 @@ public function equals($testTime, ?string $timezone = null): bool
*/
public function sameAs($testTime, ?string $timezone = null): bool
{
if ($testTime instanceof DateTimeInterface) {
$testTime = $testTime->format('Y-m-d H:i:s.u O');
} elseif (is_string($testTime)) {
$timezone = in_array($timezone, [null, '', '0'], true) ? $this->timezone : $timezone;
$timezone = $timezone instanceof DateTimeZone ? $timezone : new DateTimeZone($timezone);
$testTime = new DateTime($testTime, $timezone);
$testTime = $testTime->format('Y-m-d H:i:s.u O');
}
$testTime = $this->normalizeTime($testTime, $timezone)->format('Y-m-d H:i:s.u O');

$ourTime = $this->format('Y-m-d H:i:s.u O');

Expand Down Expand Up @@ -1024,6 +1016,67 @@ public function isAfter($testTime, ?string $timezone = null): bool
return $ourTimestamp > $testTimestamp;
}

/**
* Determines if the current instance's time is between two others.
*
* If $start is after $end, the arguments are swapped.
*
* @param DateTimeInterface|self|string $start
Copy link
Copy Markdown
Member

@paulbalandan paulbalandan May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Time and TimeLegacy extends from DateTimeImmutable and DateTime which both implement the interface, so phpstan would resolve these phpdocs as simply DateTimeInterface|string. Can we update both and make them native param types?

Copy link
Copy Markdown
Contributor

@neznaika0 neznaika0 May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TimeLegacy is deprecated since 4.3.0. Perhaps it can be removed in 4.8.0

Copy link
Copy Markdown
Member Author

@michalsn michalsn May 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

As for TimeLegacy - I'm curious to hear what others think. Should we do this now, or is it something that should wait until v5?

Copy link
Copy Markdown
Contributor

@datamweb datamweb May 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There’s a good point that has been raised here. I think it would be better if we could do this in v5.

Copy link
Copy Markdown
Member

@paulbalandan paulbalandan May 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is something I am asking myself. There's no explicit docs saying what to do for deprecated classes.

Copy link
Copy Markdown
Member Author

@michalsn michalsn May 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In theory, this is subject to depreciation rules, but I would be cautious in the entire class case.

* @param DateTimeInterface|self|string $end
* @param string|null $timezone Used only when $start or $end is a string.
*
* @throws Exception
*/
public function between($start, $end, bool $equals = true, ?string $timezone = null): bool
Comment thread
paulbalandan marked this conversation as resolved.
Outdated
{
$start = $this->normalizeTime($start, $timezone);
$end = $this->normalizeTime($end, $timezone);

if ($start->isAfter($end)) {
[$start, $end] = [$end, $start];
}

if ($equals) {
return ! $this->isBefore($start) && ! $this->isAfter($end);
}

return $this->isAfter($start) && $this->isBefore($end);
}

/**
* Returns the earlier of the current instance and the provided time.
*
* If null is provided, compares against now in the current timezone.
*
* @param DateTimeInterface|self|string|null $time
Comment thread
michalsn marked this conversation as resolved.
Outdated
* @param string|null $timezone Used only when $time is a string or null.
*
* @throws Exception
*/
public function min($time = null, ?string $timezone = null): static
{
$time = $this->normalizeTime($time, $timezone);

return $this->isAfter($time) ? $time : $this;
}

/**
* Returns the later of the current instance and the provided time.
*
* If null is provided, compares against now in the current timezone.
*
* @param DateTimeInterface|self|string|null $time
* @param string|null $timezone Used only when $time is a string or null.
*
* @throws Exception
*/
public function max($time = null, ?string $timezone = null): static
{
$time = $this->normalizeTime($time, $timezone);

return $this->isBefore($time) ? $time : $this;
}

/**
* Determines if the current instance's time is in the past.
*
Expand Down Expand Up @@ -1114,17 +1167,10 @@ public function humanize()
*/
public function difference($testTime, ?string $timezone = null)
{
if (is_string($testTime)) {
$timezone = ($timezone !== null) ? new DateTimeZone($timezone) : $this->timezone;
$testTime = new DateTime($testTime, $timezone);
} elseif ($testTime instanceof static) {
$testTime = $testTime->toDateTime();
}

assert($testTime instanceof DateTime);
$testTime = $this->normalizeTime($testTime, $timezone)->toDateTime();

if ($this->timezone->getOffset($this) !== $testTime->getTimezone()->getOffset($this)) {
$testTime = $this->getUTCObject($testTime, $timezone);
$testTime = $this->getUTCObject($testTime);
$ourTime = $this->getUTCObject($this);
} else {
$ourTime = $this->toDateTime();
Expand All @@ -1142,25 +1188,41 @@ public function difference($testTime, ?string $timezone = null)
*
* @param DateTimeInterface|self|string $time
*
* @return DateTime|static
* @return DateTime
Comment thread
michalsn marked this conversation as resolved.
Outdated
*
* @throws Exception
*/
public function getUTCObject($time, ?string $timezone = null)
{
if ($time instanceof static) {
$time = $time->toDateTime();
} elseif (is_string($time)) {
$timezone = in_array($timezone, [null, '', '0'], true) ? $this->timezone : $timezone;
$timezone = $timezone instanceof DateTimeZone ? $timezone : new DateTimeZone($timezone);
$time = new DateTime($time, $timezone);
return $this->normalizeTime($time, $timezone)
->toDateTime()
->setTimezone(new DateTimeZone('UTC'));
}

/**
* Returns a Time instance normalized to the current locale.
*
* If $time is a string, it will be parsed using the provided timezone,
* or the current instance's timezone when omitted. If null is provided,
* the current time is used in the same timezone.
*
* @param DateTimeInterface|self|string|null $time
Comment thread
michalsn marked this conversation as resolved.
Outdated
*
* @throws Exception
*/
private function normalizeTime($time, ?string $timezone = null): static
{
$timezone = in_array($timezone, [null, '', '0'], true) ? $this->timezone : $timezone;

if ($time === null) {
return static::now($timezone, $this->locale);
}

if ($time instanceof DateTime || $time instanceof DateTimeImmutable) {
$time = $time->setTimezone(new DateTimeZone('UTC'));
if ($time instanceof DateTimeInterface) {
return static::createFromInstance($time, $this->locale);
}

return $time;
return new static($time, $timezone, $this->locale);
}

/**
Expand Down
68 changes: 68 additions & 0 deletions tests/system/I18n/TimeLegacyTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -923,6 +923,74 @@ public function testAfter(): void
$this->assertTrue($time2->isAfter($time1));
}

public function testBetweenInclusive(): void
{
$time = new TimeLegacy('2024-01-01 12:00:00.123456');
$start = new TimeLegacy('2024-01-01 12:00:00.123456');
$end = new TimeLegacy('2024-01-01 12:00:01.000000');

$this->assertTrue($time->between($start, $end));
}

public function testBetweenExclusive(): void
{
$time = new TimeLegacy('2024-01-01 12:00:00.123456');
$start = new TimeLegacy('2024-01-01 12:00:00.123456');
$end = new TimeLegacy('2024-01-01 12:00:01.000000');

$this->assertFalse($time->between($start, $end, false));
}

public function testBetweenSwapsReversedBounds(): void
{
$time = TimeLegacy::parse('2024-01-01 12:30:00', 'UTC');

$this->assertTrue($time->between('2024-01-01 13:00:00', '2024-01-01 12:00:00'));
}

public function testBetweenSupportsTimezoneForStringInputs(): void
{
$time = TimeLegacy::parse('2024-01-01 12:30:00', 'UTC');

$this->assertTrue($time->between('2024-01-01 13:00:00', '2024-01-01 14:00:00', true, 'Europe/Warsaw'));
}

public function testMinWithNullUsesNow(): void
{
TimeLegacy::setTestNow('2024-01-01 12:00:00', 'UTC');

$past = TimeLegacy::parse('2024-01-01 11:59:59', 'UTC');
$future = TimeLegacy::parse('2024-01-01 12:00:01', 'UTC');

$this->assertSame($past, $past->min());
$this->assertTrue($future->min()->sameAs(TimeLegacy::now('UTC')));
}

public function testMinSupportsTimezoneForStringInputs(): void
{
$time = TimeLegacy::parse('2024-01-01 12:30:00', 'UTC');

$this->assertTrue($time->min('2024-01-01 13:00:00', 'Europe/Warsaw')->sameAs('2024-01-01 13:00:00', 'Europe/Warsaw'));
}

public function testMaxWithNullUsesNow(): void
{
TimeLegacy::setTestNow('2024-01-01 12:00:00', 'UTC');

$past = TimeLegacy::parse('2024-01-01 11:59:59', 'UTC');
$future = TimeLegacy::parse('2024-01-01 12:00:01', 'UTC');

$this->assertTrue($past->max()->sameAs(TimeLegacy::now('UTC')));
$this->assertSame($future, $future->max());
}

public function testMaxSupportsTimezoneForStringInputs(): void
{
$time = TimeLegacy::parse('2024-01-01 12:30:00', 'UTC');

$this->assertTrue($time->max('2024-01-01 13:00:00', 'Europe/Warsaw')->sameAs($time));
}

public function testHumanizeYearsSingle(): void
{
TimeLegacy::setTestNow('March 10, 2017', 'America/Chicago');
Expand Down
111 changes: 111 additions & 0 deletions tests/system/I18n/TimeTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1040,6 +1040,117 @@ public function testAfterWithMicroseconds(): void
$this->assertFalse($time2->isAfter($time1));
}

public function testBetweenInclusive(): void
{
$time = new Time('2024-01-01 12:00:00.123456');
$start = new Time('2024-01-01 12:00:00.123456');
$end = new Time('2024-01-01 12:00:01.000000');

$this->assertTrue($time->between($start, $end));
}

public function testBetweenExclusive(): void
{
$time = new Time('2024-01-01 12:00:00.123456');
$start = new Time('2024-01-01 12:00:00.123456');
$end = new Time('2024-01-01 12:00:01.000000');

$this->assertFalse($time->between($start, $end, false));
}

public function testBetweenSwapsReversedBounds(): void
{
$time = Time::parse('2024-01-01 12:30:00', 'UTC');

$this->assertTrue($time->between('2024-01-01 13:00:00', '2024-01-01 12:00:00'));
}

public function testBetweenSupportsTimezoneForStringInputs(): void
{
$time = Time::parse('2024-01-01 12:30:00', 'UTC');

$this->assertTrue($time->between('2024-01-01 13:00:00', '2024-01-01 14:00:00', true, 'Europe/Warsaw'));
}

public function testBetweenSupportsDateTimeImmutable(): void
{
$time = Time::parse('2024-01-01 12:30:00', 'UTC');
$start = new DateTimeImmutable('2024-01-01 12:00:00', new DateTimeZone('UTC'));
$end = new DateTimeImmutable('2024-01-01 13:00:00', new DateTimeZone('UTC'));

$this->assertTrue($time->between($start, $end));
}

public function testMinReturnsEarlierTime(): void
{
$time = new Time('2024-01-01 12:00:00');
$later = new Time('2024-01-01 12:00:01');

$this->assertSame($time, $time->min($later));
$this->assertTrue($later->min($time)->sameAs($time));
}

public function testMinReturnsCurrentInstanceOnEqualTime(): void
{
$time = new Time('2024-01-01 12:00:00');
$equal = new Time('2024-01-01 12:00:00');

$this->assertSame($time, $time->min($equal));
}

public function testMinSupportsTimezoneForStringInputs(): void
{
$time = Time::parse('2024-01-01 12:30:00', 'UTC');

$this->assertTrue($time->min('2024-01-01 13:00:00', 'Europe/Warsaw')->sameAs('2024-01-01 13:00:00', 'Europe/Warsaw'));
}

public function testMinWithNullUsesNow(): void
{
Time::setTestNow('2024-01-01 12:00:00', 'UTC');

$past = Time::parse('2024-01-01 11:59:59', 'UTC');
$future = Time::parse('2024-01-01 12:00:01', 'UTC');

$this->assertSame($past, $past->min());
$this->assertTrue($future->min()->sameAs(Time::now('UTC')));
}

public function testMaxReturnsLaterTime(): void
{
$time = new Time('2024-01-01 12:00:00');
$earlier = new Time('2024-01-01 11:59:59');

$this->assertSame($time, $time->max($earlier));
$this->assertTrue($earlier->max($time)->sameAs($time));
}

public function testMaxReturnsCurrentInstanceOnEqualTime(): void
{
$time = new Time('2024-01-01 12:00:00');
$equal = new Time('2024-01-01 12:00:00');

$this->assertSame($time, $time->max($equal));
}

public function testMaxSupportsTimezoneForStringInputs(): void
{
$time = Time::parse('2024-01-01 12:30:00', 'UTC');

$this->assertTrue($time->max('2024-01-01 13:00:00', 'Europe/Warsaw')->sameAs($time));
}

public function testMaxWithNullUsesNow(): void
{
Time::setTestNow('2024-01-01 12:00:00', 'UTC');

$past = Time::parse('2024-01-01 11:59:59', 'UTC');
$future = Time::parse('2024-01-01 12:00:01', 'UTC');

$this->assertTrue($past->max()->sameAs(Time::now('UTC')));
$this->assertSame($future, $future->max());
}

public function testIsPast(): void
{
Time::setTestNow('2025-12-30 12:00:00', 'Asia/Tehran');
Expand Down
1 change: 1 addition & 0 deletions user_guide_src/source/changelogs/v4.8.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -268,6 +268,7 @@ Others
- Float and Double casting now throws ``CastException::forInvalidFloatRoundingMode()`` if an rounding mode other than up, down, even or odd is provided.
- **Environment:** Added ``CodeIgniter\EnvironmentDetector`` class and corresponding ``environment`` service as a mockable wrapper around the ``ENVIRONMENT`` constant.
Framework internals that previously compared ``ENVIRONMENT`` directly now go through this service, making environment-specific branches reachable in tests via ``Services::injectMock()``. See :ref:`environment-detector-service`.
- **Time:** Added ``Time::between()``, ``Time::min()``, and ``Time::max()`` comparison helpers. See :ref:`between <time-comparing-two-times-between>`, :ref:`min <time-comparing-two-times-min>`, and :ref:`max <time-comparing-two-times-max>`.

***************
Message Changes
Expand Down
Loading
Loading