From d58d22104b8cc0dc435caaf8da003aa4ee28feed Mon Sep 17 00:00:00 2001 From: kylekatarnls Date: Tue, 19 Mar 2024 15:49:00 +0100 Subject: [PATCH 1/5] Deprecate Real diff in favor of UTC diff --- src/Carbon/CarbonInterface.php | 18 +++++++---- src/Carbon/CarbonInterval.php | 2 +- src/Carbon/Traits/Date.php | 25 +++++++++++++-- src/Carbon/Traits/Difference.php | 54 ++++++++++++++++++++++---------- 4 files changed, 73 insertions(+), 26 deletions(-) diff --git a/src/Carbon/CarbonInterface.php b/src/Carbon/CarbonInterface.php index d44b7c4574..f24311c463 100644 --- a/src/Carbon/CarbonInterface.php +++ b/src/Carbon/CarbonInterface.php @@ -1626,10 +1626,11 @@ public function diffForHumans($other = null, $syntax = null, $short = false, $pa * * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInDays($date = null, bool $absolute = false): float; + public function diffInDays($date = null, bool $absolute = false, bool $utc = false): float; /** * Get the difference in days using a filter closure rounded down. @@ -1698,20 +1699,22 @@ public function diffInMinutes($date = null, bool $absolute = false): float; * * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInMonths($date = null, bool $absolute = false): float; + public function diffInMonths($date = null, bool $absolute = false, bool $utc = false): float; /** * Get the difference in quarters rounded down. * * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInQuarters($date = null, bool $absolute = false): float; + public function diffInQuarters($date = null, bool $absolute = false, bool $utc = false): float; /** * Get the difference in seconds rounded down. @@ -1729,10 +1732,11 @@ public function diffInSeconds($date = null, bool $absolute = false): float; * century, millennium * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInUnit(Unit|string $unit, $date = null, bool $absolute = false): float; + public function diffInUnit(Unit|string $unit, $date = null, bool $absolute = false, bool $utc = false): float; /** * Get the difference in weekdays rounded down. @@ -1759,20 +1763,22 @@ public function diffInWeekendDays($date = null, bool $absolute = false): int; * * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInWeeks($date = null, bool $absolute = false): float; + public function diffInWeeks($date = null, bool $absolute = false, bool $utc = false): float; /** * Get the difference in years * * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInYears($date = null, bool $absolute = false): float; + public function diffInYears($date = null, bool $absolute = false, bool $utc = false): float; /** * @deprecated To avoid conflict between different third-party libraries, static setters should not be used. diff --git a/src/Carbon/CarbonInterval.php b/src/Carbon/CarbonInterval.php index ef01f88afe..aab960eb3c 100644 --- a/src/Carbon/CarbonInterval.php +++ b/src/Carbon/CarbonInterval.php @@ -3196,7 +3196,7 @@ private function checkIntegerValue(string $name, mixed $value): void "From 3.0.0, decimal part will no longer be truncated and will be cascaded to smaller units.\n". "- To maintain the current behavior, use explicit cast: $name((int) \$value)\n". "- To adopt the new behavior globally, call CarbonInterval::enableFloatSetters()\n", - \E_USER_DEPRECATED + \E_USER_DEPRECATED, ); } } diff --git a/src/Carbon/Traits/Date.php b/src/Carbon/Traits/Date.php index 77feb51ac8..5837f6ec73 100644 --- a/src/Carbon/Traits/Date.php +++ b/src/Carbon/Traits/Date.php @@ -2592,8 +2592,29 @@ public static function sleep(int|float $seconds): void */ public function __call(string $method, array $parameters): mixed { - if (preg_match('/^(?:diff|floatDiff)In(?:Real)?(.+)$/', $method, $match)) { - $method = 'diffIn'.$match[1]; + if (preg_match('/^(diff|floatDiff)In(Real|UTC|Utc)?(.+)$/', $method, $match)) { + $mode = strtoupper($match[2] ?? ''); + $betterMethod = $match[1] === 'floatDiff' ? str_replace('floatDiff', 'diff', $method) : null; + + if ($mode === 'REAL') { + $mode = 'UTC'; + $betterMethod = str_replace($match[1], 'UTC', $betterMethod ?? $method); + } + + if ($betterMethod) { + @trigger_error( + "Use the method $betterMethod instead to make it more explicit about what it does.\n". + 'On next major version, "float" prefix will be removed (as all diff are now returning floating numbers)'. + ' and "Real" methods will be removed in favor of "UTC" because what it actually does is to convert both'. + ' dates to UTC timezone before comparison, while by default it does it only if both dates don\'t have'. + ' exactly the same timezone (Note: 2 timezones with the same offset but different names are considered'. + ' different as it\'s not safe to assume they will always have the same offset).', + \E_USER_DEPRECATED, + ); + } + + $method = 'diffIn'.$match[3]; + $parameters['utc'] = ($mode === 'UTC'); if (method_exists($this, $method)) { return $this->$method(...$parameters); diff --git a/src/Carbon/Traits/Difference.php b/src/Carbon/Traits/Difference.php index d29c81da4d..14e8aeaa79 100644 --- a/src/Carbon/Traits/Difference.php +++ b/src/Carbon/Traits/Difference.php @@ -99,10 +99,11 @@ public function diff($date = null, bool $absolute = false, array $skip = []): Ca * century, millennium * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInUnit(Unit|string $unit, $date = null, bool $absolute = false): float + public function diffInUnit(Unit|string $unit, $date = null, bool $absolute = false, bool $utc = false): float { $unit = static::pluralUnit($unit instanceof Unit ? $unit->value : rtrim($unit, 'z')); $method = 'diffIn'.$unit; @@ -111,7 +112,7 @@ public function diffInUnit(Unit|string $unit, $date = null, bool $absolute = fal throw new UnknownUnitException($unit); } - return $this->$method($date, $absolute); + return $this->$method($date, $absolute, $utc); } /** @@ -119,18 +120,27 @@ public function diffInUnit(Unit|string $unit, $date = null, bool $absolute = fal * * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInYears($date = null, bool $absolute = false): float + public function diffInYears($date = null, bool $absolute = false, bool $utc = false): float { $start = $this; $end = $this->resolveCarbon($date); + + if ($utc) { + $start = $start->avoidMutation()->utc(); + $end = $end->avoidMutation()->utc(); + } + $ascending = ($start <= $end); $sign = $absolute || $ascending ? 1 : -1; + if (!$ascending) { [$start, $end] = [$end, $start]; } + $yearsDiff = (int) $start->diff($end, $absolute)->format('%r%y'); /** @var Carbon|CarbonImmutable $floorEnd */ $floorEnd = $start->copy()->addYears($yearsDiff); @@ -154,12 +164,13 @@ public function diffInYears($date = null, bool $absolute = false): float * * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInQuarters($date = null, bool $absolute = false): float + public function diffInQuarters($date = null, bool $absolute = false, bool $utc = false): float { - return $this->diffInMonths($date, $absolute) / static::MONTHS_PER_QUARTER; + return $this->diffInMonths($date, $absolute, $utc) / static::MONTHS_PER_QUARTER; } /** @@ -167,13 +178,20 @@ public function diffInQuarters($date = null, bool $absolute = false): float * * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInMonths($date = null, bool $absolute = false): float + public function diffInMonths($date = null, bool $absolute = false, bool $utc = false): float { $start = $this; - $end = $this->resolveCarbon($date)->avoidMutation()->setTimezone($this->tz); + $end = $this->resolveCarbon($date); + $compareUsingUtc = $utc || ($end->timezoneName !== $start->timezoneName); + + if ($compareUsingUtc) { + $start = $start->avoidMutation()->utc(); + $end = $end->avoidMutation()->utc(); + } [$yearStart, $monthStart, $dayStart] = explode('-', $start->format('Y-m-dHisu')); [$yearEnd, $monthEnd, $dayEnd] = explode('-', $end->format('Y-m-dHisu')); @@ -196,14 +214,14 @@ public function diffInMonths($date = null, bool $absolute = false): float } /** @var Carbon|CarbonImmutable $floorEnd */ - $floorEnd = $start->copy()->addMonths($monthsDiff); + $floorEnd = $start->avoidMutation()->addMonths($monthsDiff); if ($floorEnd >= $end) { return $sign * $monthsDiff; } /** @var Carbon|CarbonImmutable $startOfMonthAfterFloorEnd */ - $startOfMonthAfterFloorEnd = $floorEnd->copy()->addMonthNoOverflow()->startOfMonth(); + $startOfMonthAfterFloorEnd = $floorEnd->avoidMutation()->addMonthNoOverflow()->startOfMonth(); if ($startOfMonthAfterFloorEnd > $end) { return $sign * ($monthsDiff + $floorEnd->diffInDays($end) / $floorEnd->daysInMonth); @@ -217,12 +235,13 @@ public function diffInMonths($date = null, bool $absolute = false): float * * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInWeeks($date = null, bool $absolute = false): float + public function diffInWeeks($date = null, bool $absolute = false, bool $utc = false): float { - return $this->diffInDays($date, $absolute) / static::DAYS_PER_WEEK; + return $this->diffInDays($date, $absolute, $utc) / static::DAYS_PER_WEEK; } /** @@ -230,23 +249,24 @@ public function diffInWeeks($date = null, bool $absolute = false): float * * @param \Carbon\CarbonInterface|\DateTimeInterface|string|null $date * @param bool $absolute Get the absolute of the difference + * @param bool $utc Always convert dates to UTC before comparing (if not set, it will do it only if timezones are different) * * @return float */ - public function diffInDays($date = null, bool $absolute = false): float + public function diffInDays($date = null, bool $absolute = false, bool $utc = false): float { $date = $this->resolveCarbon($date); $current = $this; - $sameTimezone = ($date->timezoneName === $current->timezoneName); + $compareUsingUtc = $utc || ($date->timezoneName !== $current->timezoneName); - if (!$sameTimezone) { - $date = $date->copy()->utc(); - $current = $current->copy()->utc(); + if ($compareUsingUtc) { + $date = $date->avoidMutation()->utc(); + $current = $current->avoidMutation()->utc(); } $interval = $current->diffAsDateInterval($date, $absolute); - if ($sameTimezone) { + if (!$compareUsingUtc) { $minutes = $interval->i + ($interval->s + $interval->f) / static::SECONDS_PER_MINUTE; $hours = $interval->h + $minutes / static::MINUTES_PER_HOUR; From 7815557422888da8dd8564f6c6934765b2eb5428 Mon Sep 17 00:00:00 2001 From: kylekatarnls Date: Sun, 24 Mar 2024 18:49:07 +0100 Subject: [PATCH 2/5] Add utc parameters only for methods needing it (units bigger than hour) --- src/Carbon/Traits/Date.php | 8 +- tests/Carbon/DiffTest.php | 93 ++++++++++++++++++++--- tests/CarbonImmutable/DiffTest.php | 108 ++++++++++++++++++++++++--- tests/Jenssegers/TranslationTest.php | 1 - 4 files changed, 185 insertions(+), 25 deletions(-) diff --git a/src/Carbon/Traits/Date.php b/src/Carbon/Traits/Date.php index 5837f6ec73..6738ace519 100644 --- a/src/Carbon/Traits/Date.php +++ b/src/Carbon/Traits/Date.php @@ -2613,8 +2613,12 @@ public function __call(string $method, array $parameters): mixed ); } - $method = 'diffIn'.$match[3]; - $parameters['utc'] = ($mode === 'UTC'); + $unit = self::pluralUnit($match[3]); + $method = 'diffIn'.ucfirst($unit); + + if (\in_array($unit, ['days', 'weeks', 'months', 'quarters', 'years'])) { + $parameters['utc'] = ($mode === 'UTC'); + } if (method_exists($this, $method)) { return $this->$method(...$parameters); diff --git a/tests/Carbon/DiffTest.php b/tests/Carbon/DiffTest.php index b4929b3a25..00d49b760a 100644 --- a/tests/Carbon/DiffTest.php +++ b/tests/Carbon/DiffTest.php @@ -136,9 +136,11 @@ public function testDiffInMonthsWithTimezone() $this->assertSame(-1, (int) $first->diffInMonths($second, false)); $this->assertSame(1, (int) $second->diffInMonths($first, false)); - $this->assertVeryClose(-(1 + 6 / 24 / 31 + 1 / 24 / 28), $first->diffInMonths($second)); + $this->assertSame($first->utc()->diffInMonths($second->utc()), $first->diffInMonths($second)); + $this->assertSame($second->utc()->diffInMonths($first->utc()), $second->diffInMonths($first)); + $this->assertVeryClose(-(1 + 1 / 24 / 31 + 6 / 24 / 28), $first->diffInMonths($second)); // $second date in Toronto is 2021-12-31 18:00, so we have 6 hours in December (a 31 days month), and 1 hour in February (28 days month) - $this->assertVeryClose(1 + (7 / 24 / 28), $second->diffInMonths($first)); + $this->assertVeryClose(1 + 1 / 24 / 31 + 6 / 24 / 28, $second->diffInMonths($first)); // Considered in Berlin timezone, the 7 extra hours are in February (28 days month) $first = new Carbon('2022-02-01 01:00 Europe/Berlin'); @@ -146,7 +148,9 @@ public function testDiffInMonthsWithTimezone() $this->assertSame(0, (int) $first->diffInMonths($second, false)); $this->assertSame(0, (int) $second->diffInMonths($first, false)); - $this->assertVeryClose(-(1 - 6 / 24 / 31 + 1 / 24 / 28), $first->diffInMonths($second)); + $this->assertSame($first->utc()->diffInMonths($second->utc()), $first->diffInMonths($second)); + $this->assertSame($second->utc()->diffInMonths($first->utc()), $second->diffInMonths($first)); + $this->assertVeryClose(-(1 - 5 / 24 / 31), $first->diffInMonths($second)); $this->assertVeryClose(1 - 5 / 24 / 31, $second->diffInMonths($first)); } @@ -1868,10 +1872,10 @@ public function testFloatDiffWithRealUnits() date_default_timezone_set('UTC'); $this->assertVeryClose(1.0006944444444446, Carbon::parse('2018-12-01 00:00')->floatDiffInRealDays(Carbon::parse('2018-12-02 00:01'), true)); - $this->assertSame(1.0, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-03-28 20:00')); - $this->assertSame(2.0, Carbon::parse('2021-03-26 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-03-28 20:00')); - $this->assertSame(2.0, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-03-29 20:00')); - $this->assertSame(1.0, Carbon::parse('2021-10-30 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-10-31 20:00')); + $this->assertVeryClose(0.9583333333333334, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-03-28 20:00')); + $this->assertVeryClose(1.9583333333333335, Carbon::parse('2021-03-26 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-03-28 20:00')); + $this->assertVeryClose(1.9583333333333335, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-03-29 20:00')); + $this->assertVeryClose(1.0416666666666667, Carbon::parse('2021-10-30 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-10-31 20:00')); $this->assertVeryClose(1.0006944444444443, Carbon::parse('2018-12-01 00:00')->floatDiffInRealDays(Carbon::parse('2018-12-02 00:01'))); $this->assertVeryClose(1.0006944444444443, Carbon::parse('2018-12-01 00:00')->floatDiffInRealDays(Carbon::parse('2018-12-02 00:01'))); @@ -1909,16 +1913,81 @@ public function testFloatDiffWithRealUnits() $this->assertVeryClose(5.325284965308378, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInRealYears(Carbon::parse('2023-06-12 14:24:58.987421'))); $this->assertVeryClose(-5.325284965308378, Carbon::parse('2023-06-12 14:24:58.987421')->floatDiffInRealYears(Carbon::parse('2018-02-13 20:55:12.321456'))); - $this->assertSame(1.0, Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris'), true)); + $this->assertVeryClose(1.0336021505376345, Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris'), true)); $this->assertSame(1.0, Carbon::parse('2018-10-28 00:00:00')->floatDiffInRealMonths(Carbon::parse('2018-11-28 00:00:00'), true)); - $this->assertSame(1.0, Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris'), true)); + $this->assertVeryClose(1.0013888888888889, Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris'), true)); - $this->assertSame(-1.0, Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris'))); + $this->assertVeryClose(-1.0336021505376345, Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris'))); $this->assertSame(-1.0, Carbon::parse('2018-11-28 00:00:00')->floatDiffInRealMonths(Carbon::parse('2018-10-28 00:00:00'))); - $this->assertSame(-1.0, Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris'))); + $this->assertVeryClose(-1.0013888888888889, Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris'))); Carbon::setTestNow('2021-03-28 20:00 Europe/Warsaw'); - $this->assertSame(1.0, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInRealDays()); + $this->assertSame(0.9583333333333334, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInRealDays()); + } + + public function testFloatDiffWithUTCUnits() + { + $from = Carbon::parse('2021-03-27 20:00 Europe/Warsaw'); + $to = Carbon::parse('2021-03-27 20:00 Europe/London'); + $from->floatDiffInUtcDays($to); + + $this->assertSame('2021-03-27 20:00:00 Europe/Warsaw', $from->format('Y-m-d H:i:s e')); + $this->assertSame('2021-03-27 20:00:00 Europe/London', $to->format('Y-m-d H:i:s e')); + + date_default_timezone_set('UTC'); + $this->assertVeryClose(1.0006944444444446, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcDays(Carbon::parse('2018-12-02 00:01'), true)); + + $this->assertVeryClose(0.9583333333333334, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInUtcDays('2021-03-28 20:00')); + $this->assertVeryClose(1.9583333333333335, Carbon::parse('2021-03-26 20:00 Europe/Warsaw')->floatDiffInUtcDays('2021-03-28 20:00')); + $this->assertVeryClose(1.9583333333333335, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInUtcDays('2021-03-29 20:00')); + $this->assertVeryClose(1.0416666666666667, Carbon::parse('2021-10-30 20:00 Europe/Warsaw')->floatDiffInUtcDays('2021-10-31 20:00')); + $this->assertVeryClose(1.0006944444444443, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcDays(Carbon::parse('2018-12-02 00:01'))); + + $this->assertVeryClose(1.0006944444444443, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcDays(Carbon::parse('2018-12-02 00:01'))); + $this->assertVeryClose(1.0006944444444443 / 7, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcWeeks(Carbon::parse('2018-12-02 00:01'))); + + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-03-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2018-04-12 14:24:58.987421'), true)); + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-04-12 14:24:58.987421')->floatDiffInUtcMonths(Carbon::parse('2018-03-13 20:55:12.321456'), true)); + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-03-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2018-04-12 14:24:58.987421'), false)); + $this->assertVeryClose(-0.9714742503779745, Carbon::parse('2018-04-12 14:24:58.987421')->floatDiffInUtcMonths(Carbon::parse('2018-03-13 20:55:12.321456'), false)); + + $this->assertVeryClose(1.0006944444444443 / 7, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcWeeks(Carbon::parse('2018-12-02 00:01'))); + $this->assertVeryClose(1.0006944444444443 / 7, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcWeeks(Carbon::parse('2018-12-02 00:01'), true)); + + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-03-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2018-04-12 14:24:58.987421'))); + $this->assertVeryClose(-0.9714742503779745, Carbon::parse('2018-04-12 14:24:58.987421')->floatDiffInUtcMonths(Carbon::parse('2018-03-13 20:55:12.321456'))); + + $this->assertVeryClose(16.557633744585264, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2019-06-30 14:24:58.987421'), true)); + + $this->assertVeryClose(15.971474250377973, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2019-06-12 14:24:58.987421'), true)); + $this->assertVeryClose(15.971474250377973, Carbon::parse('2019-06-12 14:24:58.987421')->floatDiffInUtcMonths(Carbon::parse('2018-02-13 20:55:12.321456'), true)); + $this->assertVeryClose(15.971474250377973, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2019-06-12 14:24:58.987421'))); + $this->assertVeryClose(-15.971474250377973, Carbon::parse('2019-06-12 14:24:58.987421')->floatDiffInUtcMonths(Carbon::parse('2018-02-13 20:55:12.321456'))); + + $this->assertSame(1.0, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2019-02-13 20:55:12.321456'), true)); + $this->assertVeryClose(1.3746000338015283, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2019-06-30 14:24:58.987421'), true)); + $this->assertVeryClose(0.9609014036645421, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2019-01-30 14:24:58.987421'), true)); + + $this->assertVeryClose(1.3252849653083778, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2019-06-12 14:24:58.987421'), true)); + $this->assertVeryClose(1.3252849653083778, Carbon::parse('2019-06-12 14:24:58.987421')->floatDiffInUtcYears(Carbon::parse('2018-02-13 20:55:12.321456'), true)); + $this->assertVeryClose(1.3252849653083778, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2019-06-12 14:24:58.987421'))); + $this->assertVeryClose(-1.3252849653083778, Carbon::parse('2019-06-12 14:24:58.987421')->floatDiffInUtcYears(Carbon::parse('2018-02-13 20:55:12.321456'))); + + $this->assertVeryClose(5.325284965308378, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2023-06-12 14:24:58.987421'), true)); + $this->assertVeryClose(5.325284965308378, Carbon::parse('2023-06-12 14:24:58.987421')->floatDiffInUtcYears(Carbon::parse('2018-02-13 20:55:12.321456'), true)); + $this->assertVeryClose(5.325284965308378, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2023-06-12 14:24:58.987421'))); + $this->assertVeryClose(-5.325284965308378, Carbon::parse('2023-06-12 14:24:58.987421')->floatDiffInUtcYears(Carbon::parse('2018-02-13 20:55:12.321456'))); + + $this->assertVeryClose(1.0336021505376345, Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris')->floatDiffInUtcMonths(Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris'), true)); + $this->assertSame(1.0, Carbon::parse('2018-10-28 00:00:00')->floatDiffInUtcMonths(Carbon::parse('2018-11-28 00:00:00'), true)); + $this->assertVeryClose(1.0013888888888889, Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris')->floatDiffInUtcMonths(Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris'), true)); + + $this->assertVeryClose(-1.0336021505376345, Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris')->floatDiffInUtcMonths(Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris'))); + $this->assertSame(-1.0, Carbon::parse('2018-11-28 00:00:00')->floatDiffInUtcMonths(Carbon::parse('2018-10-28 00:00:00'))); + $this->assertVeryClose(-1.0013888888888889, Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris')->floatDiffInUtcMonths(Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris'))); + + Carbon::setTestNow('2021-03-28 20:00 Europe/Warsaw'); + $this->assertSame(0.9583333333333334, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInUtcDays()); } /** diff --git a/tests/CarbonImmutable/DiffTest.php b/tests/CarbonImmutable/DiffTest.php index 67c7207bf6..f91aeef9b5 100644 --- a/tests/CarbonImmutable/DiffTest.php +++ b/tests/CarbonImmutable/DiffTest.php @@ -1684,15 +1684,35 @@ public function testFloatDiff() public function testFloatDiffWithRealUnits() { - date_default_timezone_set('UTC'); + $from = Carbon::parse('2021-03-27 20:00 Europe/Warsaw'); + $to = Carbon::parse('2021-03-27 20:00 Europe/London'); + $from->floatDiffInRealDays($to); + + $this->assertSame('2021-03-27 20:00:00 Europe/Warsaw', $from->format('Y-m-d H:i:s e')); + $this->assertSame('2021-03-27 20:00:00 Europe/London', $to->format('Y-m-d H:i:s e')); + date_default_timezone_set('UTC'); $this->assertVeryClose(1.0006944444444446, Carbon::parse('2018-12-01 00:00')->floatDiffInRealDays(Carbon::parse('2018-12-02 00:01'), true)); - $this->assertVeryClose(1.0006944444444446 / 7, Carbon::parse('2018-12-01 00:00')->floatDiffInRealWeeks(Carbon::parse('2018-12-02 00:01'), true)); - $this->assertVeryClose(0.9714742503779743, Carbon::parse('2018-03-13 20:55:12.321456')->floatDiffInRealMonths(Carbon::parse('2018-04-12 14:24:58.987421'), true)); - $this->assertVeryClose(0.9714742503779743, Carbon::parse('2018-04-12 14:24:58.987421')->floatDiffInRealMonths(Carbon::parse('2018-03-13 20:55:12.321456'), true)); - $this->assertVeryClose(0.9714742503779743, Carbon::parse('2018-03-13 20:55:12.321456')->floatDiffInRealMonths(Carbon::parse('2018-04-12 14:24:58.987421'))); - $this->assertVeryClose(-0.9714742503779743, Carbon::parse('2018-04-12 14:24:58.987421')->floatDiffInRealMonths(Carbon::parse('2018-03-13 20:55:12.321456'))); + $this->assertVeryClose(0.9583333333333334, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-03-28 20:00')); + $this->assertVeryClose(1.9583333333333335, Carbon::parse('2021-03-26 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-03-28 20:00')); + $this->assertVeryClose(1.9583333333333335, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-03-29 20:00')); + $this->assertVeryClose(1.0416666666666667, Carbon::parse('2021-10-30 20:00 Europe/Warsaw')->floatDiffInRealDays('2021-10-31 20:00')); + $this->assertVeryClose(1.0006944444444443, Carbon::parse('2018-12-01 00:00')->floatDiffInRealDays(Carbon::parse('2018-12-02 00:01'))); + + $this->assertVeryClose(1.0006944444444443, Carbon::parse('2018-12-01 00:00')->floatDiffInRealDays(Carbon::parse('2018-12-02 00:01'))); + $this->assertVeryClose(1.0006944444444443 / 7, Carbon::parse('2018-12-01 00:00')->floatDiffInRealWeeks(Carbon::parse('2018-12-02 00:01'))); + + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-03-13 20:55:12.321456')->floatDiffInRealMonths(Carbon::parse('2018-04-12 14:24:58.987421'), true)); + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-04-12 14:24:58.987421')->floatDiffInRealMonths(Carbon::parse('2018-03-13 20:55:12.321456'), true)); + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-03-13 20:55:12.321456')->floatDiffInRealMonths(Carbon::parse('2018-04-12 14:24:58.987421'), false)); + $this->assertVeryClose(-0.9714742503779745, Carbon::parse('2018-04-12 14:24:58.987421')->floatDiffInRealMonths(Carbon::parse('2018-03-13 20:55:12.321456'), false)); + + $this->assertVeryClose(1.0006944444444443 / 7, Carbon::parse('2018-12-01 00:00')->floatDiffInRealWeeks(Carbon::parse('2018-12-02 00:01'))); + $this->assertVeryClose(1.0006944444444443 / 7, Carbon::parse('2018-12-01 00:00')->floatDiffInRealWeeks(Carbon::parse('2018-12-02 00:01'), true)); + + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-03-13 20:55:12.321456')->floatDiffInRealMonths(Carbon::parse('2018-04-12 14:24:58.987421'))); + $this->assertVeryClose(-0.9714742503779745, Carbon::parse('2018-04-12 14:24:58.987421')->floatDiffInRealMonths(Carbon::parse('2018-03-13 20:55:12.321456'))); $this->assertVeryClose(16.557633744585264, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInRealMonths(Carbon::parse('2019-06-30 14:24:58.987421'), true)); @@ -1715,13 +1735,81 @@ public function testFloatDiffWithRealUnits() $this->assertVeryClose(5.325284965308378, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInRealYears(Carbon::parse('2023-06-12 14:24:58.987421'))); $this->assertVeryClose(-5.325284965308378, Carbon::parse('2023-06-12 14:24:58.987421')->floatDiffInRealYears(Carbon::parse('2018-02-13 20:55:12.321456'))); - $this->assertSame(1.0, Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris'), true)); + $this->assertVeryClose(1.0336021505376345, Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris'), true)); $this->assertSame(1.0, Carbon::parse('2018-10-28 00:00:00')->floatDiffInRealMonths(Carbon::parse('2018-11-28 00:00:00'), true)); - $this->assertSame(1.0, Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris'), true)); + $this->assertVeryClose(1.0013888888888889, Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris'), true)); - $this->assertSame(-1.0, Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris'))); + $this->assertVeryClose(-1.0336021505376345, Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris'))); $this->assertSame(-1.0, Carbon::parse('2018-11-28 00:00:00')->floatDiffInRealMonths(Carbon::parse('2018-10-28 00:00:00'))); - $this->assertSame(-1.0, Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris'))); + $this->assertVeryClose(-1.0013888888888889, Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris')->floatDiffInRealMonths(Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris'))); + + Carbon::setTestNow('2021-03-28 20:00 Europe/Warsaw'); + $this->assertSame(0.9583333333333334, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInRealDays()); + } + + public function testFloatDiffWithUTCUnits() + { + $from = Carbon::parse('2021-03-27 20:00 Europe/Warsaw'); + $to = Carbon::parse('2021-03-27 20:00 Europe/London'); + $from->floatDiffInUtcDays($to); + + $this->assertSame('2021-03-27 20:00:00 Europe/Warsaw', $from->format('Y-m-d H:i:s e')); + $this->assertSame('2021-03-27 20:00:00 Europe/London', $to->format('Y-m-d H:i:s e')); + + date_default_timezone_set('UTC'); + $this->assertVeryClose(1.0006944444444446, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcDays(Carbon::parse('2018-12-02 00:01'), true)); + + $this->assertVeryClose(0.9583333333333334, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInUtcDays('2021-03-28 20:00')); + $this->assertVeryClose(1.9583333333333335, Carbon::parse('2021-03-26 20:00 Europe/Warsaw')->floatDiffInUtcDays('2021-03-28 20:00')); + $this->assertVeryClose(1.9583333333333335, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInUtcDays('2021-03-29 20:00')); + $this->assertVeryClose(1.0416666666666667, Carbon::parse('2021-10-30 20:00 Europe/Warsaw')->floatDiffInUtcDays('2021-10-31 20:00')); + $this->assertVeryClose(1.0006944444444443, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcDays(Carbon::parse('2018-12-02 00:01'))); + + $this->assertVeryClose(1.0006944444444443, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcDays(Carbon::parse('2018-12-02 00:01'))); + $this->assertVeryClose(1.0006944444444443 / 7, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcWeeks(Carbon::parse('2018-12-02 00:01'))); + + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-03-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2018-04-12 14:24:58.987421'), true)); + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-04-12 14:24:58.987421')->floatDiffInUtcMonths(Carbon::parse('2018-03-13 20:55:12.321456'), true)); + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-03-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2018-04-12 14:24:58.987421'), false)); + $this->assertVeryClose(-0.9714742503779745, Carbon::parse('2018-04-12 14:24:58.987421')->floatDiffInUtcMonths(Carbon::parse('2018-03-13 20:55:12.321456'), false)); + + $this->assertVeryClose(1.0006944444444443 / 7, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcWeeks(Carbon::parse('2018-12-02 00:01'))); + $this->assertVeryClose(1.0006944444444443 / 7, Carbon::parse('2018-12-01 00:00')->floatDiffInUtcWeeks(Carbon::parse('2018-12-02 00:01'), true)); + + $this->assertVeryClose(0.9714742503779745, Carbon::parse('2018-03-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2018-04-12 14:24:58.987421'))); + $this->assertVeryClose(-0.9714742503779745, Carbon::parse('2018-04-12 14:24:58.987421')->floatDiffInUtcMonths(Carbon::parse('2018-03-13 20:55:12.321456'))); + + $this->assertVeryClose(16.557633744585264, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2019-06-30 14:24:58.987421'), true)); + + $this->assertVeryClose(15.971474250377973, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2019-06-12 14:24:58.987421'), true)); + $this->assertVeryClose(15.971474250377973, Carbon::parse('2019-06-12 14:24:58.987421')->floatDiffInUtcMonths(Carbon::parse('2018-02-13 20:55:12.321456'), true)); + $this->assertVeryClose(15.971474250377973, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcMonths(Carbon::parse('2019-06-12 14:24:58.987421'))); + $this->assertVeryClose(-15.971474250377973, Carbon::parse('2019-06-12 14:24:58.987421')->floatDiffInUtcMonths(Carbon::parse('2018-02-13 20:55:12.321456'))); + + $this->assertSame(1.0, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2019-02-13 20:55:12.321456'), true)); + $this->assertVeryClose(1.3746000338015283, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2019-06-30 14:24:58.987421'), true)); + $this->assertVeryClose(0.9609014036645421, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2019-01-30 14:24:58.987421'), true)); + + $this->assertVeryClose(1.3252849653083778, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2019-06-12 14:24:58.987421'), true)); + $this->assertVeryClose(1.3252849653083778, Carbon::parse('2019-06-12 14:24:58.987421')->floatDiffInUtcYears(Carbon::parse('2018-02-13 20:55:12.321456'), true)); + $this->assertVeryClose(1.3252849653083778, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2019-06-12 14:24:58.987421'))); + $this->assertVeryClose(-1.3252849653083778, Carbon::parse('2019-06-12 14:24:58.987421')->floatDiffInUtcYears(Carbon::parse('2018-02-13 20:55:12.321456'))); + + $this->assertVeryClose(5.325284965308378, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2023-06-12 14:24:58.987421'), true)); + $this->assertVeryClose(5.325284965308378, Carbon::parse('2023-06-12 14:24:58.987421')->floatDiffInUtcYears(Carbon::parse('2018-02-13 20:55:12.321456'), true)); + $this->assertVeryClose(5.325284965308378, Carbon::parse('2018-02-13 20:55:12.321456')->floatDiffInUtcYears(Carbon::parse('2023-06-12 14:24:58.987421'))); + $this->assertVeryClose(-5.325284965308378, Carbon::parse('2023-06-12 14:24:58.987421')->floatDiffInUtcYears(Carbon::parse('2018-02-13 20:55:12.321456'))); + + $this->assertVeryClose(1.0336021505376345, Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris')->floatDiffInUtcMonths(Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris'), true)); + $this->assertSame(1.0, Carbon::parse('2018-10-28 00:00:00')->floatDiffInUtcMonths(Carbon::parse('2018-11-28 00:00:00'), true)); + $this->assertVeryClose(1.0013888888888889, Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris')->floatDiffInUtcMonths(Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris'), true)); + + $this->assertVeryClose(-1.0336021505376345, Carbon::parse('2018-11-01 00:00:00', 'Europe/Paris')->floatDiffInUtcMonths(Carbon::parse('2018-10-01 00:00:00', 'Europe/Paris'))); + $this->assertSame(-1.0, Carbon::parse('2018-11-28 00:00:00')->floatDiffInUtcMonths(Carbon::parse('2018-10-28 00:00:00'))); + $this->assertVeryClose(-1.0013888888888889, Carbon::parse('2018-11-28 00:00:00', 'Europe/Paris')->floatDiffInUtcMonths(Carbon::parse('2018-10-28 00:00:00', 'Europe/Paris'))); + + Carbon::setTestNow('2021-03-28 20:00 Europe/Warsaw'); + $this->assertSame(0.9583333333333334, Carbon::parse('2021-03-27 20:00 Europe/Warsaw')->floatDiffInUtcDays()); } /** diff --git a/tests/Jenssegers/TranslationTest.php b/tests/Jenssegers/TranslationTest.php index 809c650b3d..555bdd1ace 100644 --- a/tests/Jenssegers/TranslationTest.php +++ b/tests/Jenssegers/TranslationTest.php @@ -77,7 +77,6 @@ public function testCustomSuffix() $this->assertSame('vor 5 Sekunden', $date->ago()); } - /** @group i */ public function testTimespanTranslated() { JenssegersDate::setLocale('nl'); From d735797a4b4d1a0d4e1e96cbc0897aa769aa70ac Mon Sep 17 00:00:00 2001 From: kylekatarnls Date: Sun, 24 Mar 2024 19:15:57 +0100 Subject: [PATCH 3/5] Update dependencies --- composer.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/composer.json b/composer.json index f71568b397..d4a00ffd85 100644 --- a/composer.json +++ b/composer.json @@ -51,14 +51,14 @@ "require-dev": { "doctrine/dbal": "^3.6.3 || ^4.0", "doctrine/orm": "^2.15.2 || ^3.0", - "friendsofphp/php-cs-fixer": "^3.18.0", - "kylekatarnls/multi-tester": "^2.2.0", - "ondrejmirtes/better-reflection": "^6.11.0.0", - "phpmd/phpmd": "^2.13.0", - "phpstan/extension-installer": "^1.3.0", - "phpstan/phpstan": "^1.10.20", - "phpunit/phpunit": "^10.2.2", - "squizlabs/php_codesniffer": "^3.7.2" + "friendsofphp/php-cs-fixer": "^3.52.1", + "kylekatarnls/multi-tester": "^2.5.3", + "ondrejmirtes/better-reflection": "^6.25.0.4", + "phpmd/phpmd": "^2.15.0", + "phpstan/extension-installer": "^1.3.1", + "phpstan/phpstan": "^1.10.65", + "phpunit/phpunit": "^10.5.15", + "squizlabs/php_codesniffer": "^3.9.0" }, "provide": { "psr/clock-implementation": "1.0" From d504c0852de7d1fc933f20343c4b3308c8ed9d01 Mon Sep 17 00:00:00 2001 From: kylekatarnls Date: Wed, 27 Mar 2024 13:15:42 +0100 Subject: [PATCH 4/5] Downgrade nikic/php-parser in CI --- .github/workflows/tests.yml | 10 ++-- phpdoc.php | 12 ++--- src/Carbon/Traits/Units.php | 68 ++++++++++++++++++++-------- tests/PHPStan/MacroExtensionTest.php | 2 +- 4 files changed, 64 insertions(+), 28 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 42a4f99acc..6bef6abd52 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -63,11 +63,15 @@ jobs: - name: Select PHPUnit version if: matrix.phpunit - run: composer require --no-update phpunit/phpunit:^${{ matrix.phpunit }} --no-interaction --dev + run: composer require --no-update --no-interaction --dev "phpunit/phpunit:^${{ matrix.phpunit }}" - name: Remove conflicting optional dependencies if: matrix.phpunit >= 11 - run: composer remove --no-update ondrejmirtes/better-reflection --no-interaction --dev + run: composer remove --no-update --no-interaction --dev ondrejmirtes/better-reflection + + - name: Downgrade nikic/php-parser + if: matrix.phpunit < 11 + run: composer require --no-update --no-interaction --dev "nikic/php-parser:^4" - name: Install dependencies uses: nick-fields/retry@v3 @@ -76,7 +80,7 @@ jobs: timeout_minutes: 10 max_attempts: 3 command: | - composer remove --no-update phpmd/phpmd friendsofphp/php-cs-fixer kylekatarnls/multi-tester --no-interaction --dev; + composer remove --no-update --no-interaction --dev phpmd/phpmd friendsofphp/php-cs-fixer kylekatarnls/multi-tester; composer update --prefer-dist --no-progress --prefer-${{ matrix.setup || 'stable' }} ${{ matrix.classmap-authoritative && '--classmap-authoritative' || '' }}${{ matrix.php >= 8.2 && ' --ignore-platform-reqs' || '' }}; - name: Run test suite diff --git a/phpdoc.php b/phpdoc.php index 18f892909e..1797797211 100644 --- a/phpdoc.php +++ b/phpdoc.php @@ -26,7 +26,7 @@ ['call', 'isSameUnit'], ['call', 'setUnit'], ['call', 'addUnit'], - ['call', 'addRealUnit'], + ['call', 'addUTCUnit'], ['call', 'roundUnit'], ['call', 'diffForHumans'], ]; @@ -418,7 +418,7 @@ function dumpParameter(string $method, ReflectionParameter $parameter): string break; - case 'addRealUnit': + case 'addUTCUnit': $unit = $vars->name; $unitName = unitName($unit); $plUnit = pluralize($unit); @@ -426,25 +426,25 @@ function dumpParameter(string $method, ReflectionParameter $parameter): string $autoDocLines[] = [ '@method', 'self', - 'addReal'.ucFirst($plUnit).'(int|float $value = 1)', + 'addUTC'.ucFirst($plUnit).'(int|float $value = 1)', "Add $plUnitName (the \$value count passed in) to the instance (using timestamp).", ]; $autoDocLines[] = [ '@method', 'self', - 'addReal'.ucFirst($unit).'()', + 'addUTC'.ucFirst($unit).'()', "Add one $unitName to the instance (using timestamp).", ]; $autoDocLines[] = [ '@method', 'self', - 'subReal'.ucFirst($plUnit).'(int|float $value = 1)', + 'subUTC'.ucFirst($plUnit).'(int|float $value = 1)', "Sub $plUnitName (the \$value count passed in) to the instance (using timestamp).", ]; $autoDocLines[] = [ '@method', 'self', - 'subReal'.ucFirst($unit).'()', + 'subUTC'.ucFirst($unit).'()', "Sub one $unitName to the instance (using timestamp).", ]; $autoDocLines[] = [ diff --git a/src/Carbon/Traits/Units.php b/src/Carbon/Traits/Units.php index d8434dab4e..25c1c4f85a 100644 --- a/src/Carbon/Traits/Units.php +++ b/src/Carbon/Traits/Units.php @@ -34,6 +34,8 @@ trait Units { /** + * @deprecated Prefer to use add addUTCUnit() which more accurately defines what it's doing. + * * Add seconds to the instance using timestamp. Positive $value travels * forward while negative $value travels into the past. * @@ -43,14 +45,28 @@ trait Units * @return static */ public function addRealUnit(string $unit, $value = 1): static + { + return $this->addUTCUnit($unit, $value); + } + + /** + * Add seconds to the instance using timestamp. Positive $value travels + * forward while negative $value travels into the past. + * + * @param string $unit + * @param int|float|null $value + * + * @return static + */ + public function addUTCUnit(string $unit, $value = 1): static { $value ??= 0; switch ($unit) { - // @call addRealUnit + // @call addUTCUnit case 'micro': - // @call addRealUnit + // @call addUTCUnit case 'microsecond': /* @var CarbonInterface $this */ $diff = $this->microsecond + $value; @@ -63,71 +79,71 @@ public function addRealUnit(string $unit, $value = 1): static return $this->tz('UTC')->modify("@$time.$microtime")->setTimezone($timezone); - // @call addRealUnit + // @call addUTCUnit case 'milli': - // @call addRealUnit + // @call addUTCUnit case 'millisecond': - return $this->addRealUnit('microsecond', $value * static::MICROSECONDS_PER_MILLISECOND); + return $this->addUTCUnit('microsecond', $value * static::MICROSECONDS_PER_MILLISECOND); - // @call addRealUnit + // @call addUTCUnit case 'second': break; - // @call addRealUnit + // @call addUTCUnit case 'minute': $value *= static::SECONDS_PER_MINUTE; break; - // @call addRealUnit + // @call addUTCUnit case 'hour': $value *= static::MINUTES_PER_HOUR * static::SECONDS_PER_MINUTE; break; - // @call addRealUnit + // @call addUTCUnit case 'day': $value *= static::HOURS_PER_DAY * static::MINUTES_PER_HOUR * static::SECONDS_PER_MINUTE; break; - // @call addRealUnit + // @call addUTCUnit case 'week': $value *= static::DAYS_PER_WEEK * static::HOURS_PER_DAY * static::MINUTES_PER_HOUR * static::SECONDS_PER_MINUTE; break; - // @call addRealUnit + // @call addUTCUnit case 'month': $value *= 30 * static::HOURS_PER_DAY * static::MINUTES_PER_HOUR * static::SECONDS_PER_MINUTE; break; - // @call addRealUnit + // @call addUTCUnit case 'quarter': $value *= static::MONTHS_PER_QUARTER * 30 * static::HOURS_PER_DAY * static::MINUTES_PER_HOUR * static::SECONDS_PER_MINUTE; break; - // @call addRealUnit + // @call addUTCUnit case 'year': $value *= 365 * static::HOURS_PER_DAY * static::MINUTES_PER_HOUR * static::SECONDS_PER_MINUTE; break; - // @call addRealUnit + // @call addUTCUnit case 'decade': $value *= static::YEARS_PER_DECADE * 365 * static::HOURS_PER_DAY * static::MINUTES_PER_HOUR * static::SECONDS_PER_MINUTE; break; - // @call addRealUnit + // @call addUTCUnit case 'century': $value *= static::YEARS_PER_CENTURY * 365 * static::HOURS_PER_DAY * static::MINUTES_PER_HOUR * static::SECONDS_PER_MINUTE; break; - // @call addRealUnit + // @call addUTCUnit case 'millennium': $value *= static::YEARS_PER_MILLENNIUM * 365 * static::HOURS_PER_DAY * static::MINUTES_PER_HOUR * static::SECONDS_PER_MINUTE; @@ -147,10 +163,12 @@ public function addRealUnit(string $unit, $value = 1): static ); $date = $this->setTimestamp($this->getTimestamp() + $seconds); - return $microseconds ? $date->addRealUnit('microsecond', $microseconds) : $date; + return $microseconds ? $date->addUTCUnit('microsecond', $microseconds) : $date; } /** + * @deprecated Prefer to use add subUTCUnit() which more accurately defines what it's doing. + * * Subtract seconds to the instance using timestamp. Positive $value travels * into the past while negative $value travels forward. * @@ -161,7 +179,21 @@ public function addRealUnit(string $unit, $value = 1): static */ public function subRealUnit($unit, $value = 1): static { - return $this->addRealUnit($unit, -$value); + return $this->addUTCUnit($unit, -$value); + } + + /** + * Subtract seconds to the instance using timestamp. Positive $value travels + * into the past while negative $value travels forward. + * + * @param string $unit + * @param int $value + * + * @return static + */ + public function subUTCUnit($unit, $value = 1): static + { + return $this->addUTCUnit($unit, -$value); } /** diff --git a/tests/PHPStan/MacroExtensionTest.php b/tests/PHPStan/MacroExtensionTest.php index 3491d1b180..8e4ce719e9 100644 --- a/tests/PHPStan/MacroExtensionTest.php +++ b/tests/PHPStan/MacroExtensionTest.php @@ -22,6 +22,7 @@ use PHPUnit\Framework\Attributes\RequiresPhpunit; use Tests\AbstractTestCase; +#[RequiresPhpunit('<11')] class MacroExtensionTest extends AbstractTestCase { private function mockReflectionProvider() @@ -71,7 +72,6 @@ public function testHasMacro() $this->assertFalse($scanner->hasMethod(CarbonInterface::class, 'foo')); } - #[RequiresPhpunit('<11')] public function testGetMacro() { $scanner = new MacroScanner($this->mockReflectionProvider()); From 41b550c65ff3fd05f97d1ce483afd551373920de Mon Sep 17 00:00:00 2001 From: kylekatarnls Date: Wed, 27 Mar 2024 16:37:43 +0100 Subject: [PATCH 5/5] Implement UTC variants for add/sub methods --- .github/workflows/tests.yml | 2 + phpdoc.php | 6 + phpstan.neon | 1 + src/Carbon/Carbon.php | 135 ++++++++++++---------- src/Carbon/CarbonImmutable.php | 135 ++++++++++++---------- src/Carbon/CarbonInterface.php | 161 +++++++++++++++++---------- src/Carbon/Traits/Date.php | 153 ++++++++++++++----------- tests/Carbon/IsTest.php | 2 - tests/Carbon/ModifyTest.php | 13 ++- tests/CarbonImmutable/IsTest.php | 2 - tests/CarbonImmutable/ModifyTest.php | 2 - tests/CarbonInterval/AddTest.php | 2 - 12 files changed, 361 insertions(+), 253 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 6bef6abd52..5e038050f1 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -63,6 +63,7 @@ jobs: - name: Select PHPUnit version if: matrix.phpunit + shell: bash run: composer require --no-update --no-interaction --dev "phpunit/phpunit:^${{ matrix.phpunit }}" - name: Remove conflicting optional dependencies @@ -71,6 +72,7 @@ jobs: - name: Downgrade nikic/php-parser if: matrix.phpunit < 11 + shell: bash run: composer require --no-update --no-interaction --dev "nikic/php-parser:^4" - name: Install dependencies diff --git a/phpdoc.php b/phpdoc.php index 1797797211..8c2568737b 100644 --- a/phpdoc.php +++ b/phpdoc.php @@ -453,6 +453,12 @@ function dumpParameter(string $method, ReflectionParameter $parameter): string $plUnit.'Until($endDate = null, int|float $factor = 1)', "Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each $unitName or every X $plUnitName if a factor is given.", ]; + $autoDocLines[] = [ + '@method', + 'float', + 'diffInUTC'.ucFirst($plUnit).'(DateTimeInterface|string|null $date, bool $absolute = false)', + "Convert current and given date in UTC timezone and return a floating number of $plUnitName.", + ]; break; diff --git a/phpstan.neon b/phpstan.neon index 792ed9fa20..bd6c822135 100644 --- a/phpstan.neon +++ b/phpstan.neon @@ -18,6 +18,7 @@ parameters: - '#^Call to an undefined static method#' - '#^Call to an undefined method Carbon\\Carbon(Immutable)?::floatDiffIn([A-Za-z]+)\(\)\.$#' - '#^Call to an undefined method Carbon\\Carbon(Immutable)?::diffInReal([A-Za-z]+)\(\)\.$#' + - '#^Call to an undefined method Carbon\\Carbon(Immutable)?::(add|sub)Real([A-Za-z]+)\(\)\.$#' - '#^Unsafe usage of new static\(\)\.$#' - '#^Method Carbon\\Carbon(Interface|Immutable)?::(add|sub)[A-Z][A-Za-z]+\(\) invoked with 1 parameter, 0 required\.$#' - '#^Call to an undefined method Carbon\\Carbon(Interface|Immutable)?::(super|noThis|toAppTz|copyWithAppTz)\(\)\.$#' diff --git a/src/Carbon/Carbon.php b/src/Carbon/Carbon.php index 298100583b..8364e84125 100644 --- a/src/Carbon/Carbon.php +++ b/src/Carbon/Carbon.php @@ -506,81 +506,96 @@ * @method $this addWeekday() Add one weekday to the instance (using date interval). * @method $this subWeekdays(int|float $value = 1) Sub weekdays (the $value count passed in) to the instance (using date interval). * @method $this subWeekday() Sub one weekday to the instance (using date interval). - * @method $this addRealMicros(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). - * @method $this addRealMicro() Add one microsecond to the instance (using timestamp). - * @method $this subRealMicros(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). - * @method $this subRealMicro() Sub one microsecond to the instance (using timestamp). + * @method $this addUTCMicros(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCMicro() Add one microsecond to the instance (using timestamp). + * @method $this subUTCMicros(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCMicro() Sub one microsecond to the instance (using timestamp). * @method CarbonPeriod microsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each microsecond or every X microseconds if a factor is given. - * @method $this addRealMicroseconds(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). - * @method $this addRealMicrosecond() Add one microsecond to the instance (using timestamp). - * @method $this subRealMicroseconds(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). - * @method $this subRealMicrosecond() Sub one microsecond to the instance (using timestamp). + * @method float diffInUTCMicros(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of microseconds. + * @method $this addUTCMicroseconds(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCMicrosecond() Add one microsecond to the instance (using timestamp). + * @method $this subUTCMicroseconds(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCMicrosecond() Sub one microsecond to the instance (using timestamp). * @method CarbonPeriod microsecondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each microsecond or every X microseconds if a factor is given. - * @method $this addRealMillis(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). - * @method $this addRealMilli() Add one millisecond to the instance (using timestamp). - * @method $this subRealMillis(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). - * @method $this subRealMilli() Sub one millisecond to the instance (using timestamp). + * @method float diffInUTCMicroseconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of microseconds. + * @method $this addUTCMillis(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCMilli() Add one millisecond to the instance (using timestamp). + * @method $this subUTCMillis(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCMilli() Sub one millisecond to the instance (using timestamp). * @method CarbonPeriod millisUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millisecond or every X milliseconds if a factor is given. - * @method $this addRealMilliseconds(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). - * @method $this addRealMillisecond() Add one millisecond to the instance (using timestamp). - * @method $this subRealMilliseconds(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). - * @method $this subRealMillisecond() Sub one millisecond to the instance (using timestamp). + * @method float diffInUTCMillis(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of milliseconds. + * @method $this addUTCMilliseconds(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCMillisecond() Add one millisecond to the instance (using timestamp). + * @method $this subUTCMilliseconds(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCMillisecond() Sub one millisecond to the instance (using timestamp). * @method CarbonPeriod millisecondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millisecond or every X milliseconds if a factor is given. - * @method $this addRealSeconds(int|float $value = 1) Add seconds (the $value count passed in) to the instance (using timestamp). - * @method $this addRealSecond() Add one second to the instance (using timestamp). - * @method $this subRealSeconds(int|float $value = 1) Sub seconds (the $value count passed in) to the instance (using timestamp). - * @method $this subRealSecond() Sub one second to the instance (using timestamp). + * @method float diffInUTCMilliseconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of milliseconds. + * @method $this addUTCSeconds(int|float $value = 1) Add seconds (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCSecond() Add one second to the instance (using timestamp). + * @method $this subUTCSeconds(int|float $value = 1) Sub seconds (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCSecond() Sub one second to the instance (using timestamp). * @method CarbonPeriod secondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each second or every X seconds if a factor is given. - * @method $this addRealMinutes(int|float $value = 1) Add minutes (the $value count passed in) to the instance (using timestamp). - * @method $this addRealMinute() Add one minute to the instance (using timestamp). - * @method $this subRealMinutes(int|float $value = 1) Sub minutes (the $value count passed in) to the instance (using timestamp). - * @method $this subRealMinute() Sub one minute to the instance (using timestamp). + * @method float diffInUTCSeconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of seconds. + * @method $this addUTCMinutes(int|float $value = 1) Add minutes (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCMinute() Add one minute to the instance (using timestamp). + * @method $this subUTCMinutes(int|float $value = 1) Sub minutes (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCMinute() Sub one minute to the instance (using timestamp). * @method CarbonPeriod minutesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each minute or every X minutes if a factor is given. - * @method $this addRealHours(int|float $value = 1) Add hours (the $value count passed in) to the instance (using timestamp). - * @method $this addRealHour() Add one hour to the instance (using timestamp). - * @method $this subRealHours(int|float $value = 1) Sub hours (the $value count passed in) to the instance (using timestamp). - * @method $this subRealHour() Sub one hour to the instance (using timestamp). + * @method float diffInUTCMinutes(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of minutes. + * @method $this addUTCHours(int|float $value = 1) Add hours (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCHour() Add one hour to the instance (using timestamp). + * @method $this subUTCHours(int|float $value = 1) Sub hours (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCHour() Sub one hour to the instance (using timestamp). * @method CarbonPeriod hoursUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each hour or every X hours if a factor is given. - * @method $this addRealDays(int|float $value = 1) Add days (the $value count passed in) to the instance (using timestamp). - * @method $this addRealDay() Add one day to the instance (using timestamp). - * @method $this subRealDays(int|float $value = 1) Sub days (the $value count passed in) to the instance (using timestamp). - * @method $this subRealDay() Sub one day to the instance (using timestamp). + * @method float diffInUTCHours(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of hours. + * @method $this addUTCDays(int|float $value = 1) Add days (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCDay() Add one day to the instance (using timestamp). + * @method $this subUTCDays(int|float $value = 1) Sub days (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCDay() Sub one day to the instance (using timestamp). * @method CarbonPeriod daysUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each day or every X days if a factor is given. - * @method $this addRealWeeks(int|float $value = 1) Add weeks (the $value count passed in) to the instance (using timestamp). - * @method $this addRealWeek() Add one week to the instance (using timestamp). - * @method $this subRealWeeks(int|float $value = 1) Sub weeks (the $value count passed in) to the instance (using timestamp). - * @method $this subRealWeek() Sub one week to the instance (using timestamp). + * @method float diffInUTCDays(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of days. + * @method $this addUTCWeeks(int|float $value = 1) Add weeks (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCWeek() Add one week to the instance (using timestamp). + * @method $this subUTCWeeks(int|float $value = 1) Sub weeks (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCWeek() Sub one week to the instance (using timestamp). * @method CarbonPeriod weeksUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each week or every X weeks if a factor is given. - * @method $this addRealMonths(int|float $value = 1) Add months (the $value count passed in) to the instance (using timestamp). - * @method $this addRealMonth() Add one month to the instance (using timestamp). - * @method $this subRealMonths(int|float $value = 1) Sub months (the $value count passed in) to the instance (using timestamp). - * @method $this subRealMonth() Sub one month to the instance (using timestamp). + * @method float diffInUTCWeeks(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of weeks. + * @method $this addUTCMonths(int|float $value = 1) Add months (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCMonth() Add one month to the instance (using timestamp). + * @method $this subUTCMonths(int|float $value = 1) Sub months (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCMonth() Sub one month to the instance (using timestamp). * @method CarbonPeriod monthsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each month or every X months if a factor is given. - * @method $this addRealQuarters(int|float $value = 1) Add quarters (the $value count passed in) to the instance (using timestamp). - * @method $this addRealQuarter() Add one quarter to the instance (using timestamp). - * @method $this subRealQuarters(int|float $value = 1) Sub quarters (the $value count passed in) to the instance (using timestamp). - * @method $this subRealQuarter() Sub one quarter to the instance (using timestamp). + * @method float diffInUTCMonths(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of months. + * @method $this addUTCQuarters(int|float $value = 1) Add quarters (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCQuarter() Add one quarter to the instance (using timestamp). + * @method $this subUTCQuarters(int|float $value = 1) Sub quarters (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCQuarter() Sub one quarter to the instance (using timestamp). * @method CarbonPeriod quartersUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each quarter or every X quarters if a factor is given. - * @method $this addRealYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using timestamp). - * @method $this addRealYear() Add one year to the instance (using timestamp). - * @method $this subRealYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using timestamp). - * @method $this subRealYear() Sub one year to the instance (using timestamp). + * @method float diffInUTCQuarters(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of quarters. + * @method $this addUTCYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCYear() Add one year to the instance (using timestamp). + * @method $this subUTCYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCYear() Sub one year to the instance (using timestamp). * @method CarbonPeriod yearsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each year or every X years if a factor is given. - * @method $this addRealDecades(int|float $value = 1) Add decades (the $value count passed in) to the instance (using timestamp). - * @method $this addRealDecade() Add one decade to the instance (using timestamp). - * @method $this subRealDecades(int|float $value = 1) Sub decades (the $value count passed in) to the instance (using timestamp). - * @method $this subRealDecade() Sub one decade to the instance (using timestamp). + * @method float diffInUTCYears(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of years. + * @method $this addUTCDecades(int|float $value = 1) Add decades (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCDecade() Add one decade to the instance (using timestamp). + * @method $this subUTCDecades(int|float $value = 1) Sub decades (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCDecade() Sub one decade to the instance (using timestamp). * @method CarbonPeriod decadesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each decade or every X decades if a factor is given. - * @method $this addRealCenturies(int|float $value = 1) Add centuries (the $value count passed in) to the instance (using timestamp). - * @method $this addRealCentury() Add one century to the instance (using timestamp). - * @method $this subRealCenturies(int|float $value = 1) Sub centuries (the $value count passed in) to the instance (using timestamp). - * @method $this subRealCentury() Sub one century to the instance (using timestamp). + * @method float diffInUTCDecades(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of decades. + * @method $this addUTCCenturies(int|float $value = 1) Add centuries (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCCentury() Add one century to the instance (using timestamp). + * @method $this subUTCCenturies(int|float $value = 1) Sub centuries (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCCentury() Sub one century to the instance (using timestamp). * @method CarbonPeriod centuriesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each century or every X centuries if a factor is given. - * @method $this addRealMillennia(int|float $value = 1) Add millennia (the $value count passed in) to the instance (using timestamp). - * @method $this addRealMillennium() Add one millennium to the instance (using timestamp). - * @method $this subRealMillennia(int|float $value = 1) Sub millennia (the $value count passed in) to the instance (using timestamp). - * @method $this subRealMillennium() Sub one millennium to the instance (using timestamp). + * @method float diffInUTCCenturies(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of centuries. + * @method $this addUTCMillennia(int|float $value = 1) Add millennia (the $value count passed in) to the instance (using timestamp). + * @method $this addUTCMillennium() Add one millennium to the instance (using timestamp). + * @method $this subUTCMillennia(int|float $value = 1) Sub millennia (the $value count passed in) to the instance (using timestamp). + * @method $this subUTCMillennium() Sub one millennium to the instance (using timestamp). * @method CarbonPeriod millenniaUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millennium or every X millennia if a factor is given. + * @method float diffInUTCMillennia(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of millennia. * @method $this roundYear(float $precision = 1, string $function = "round") Round the current instance year with given precision using the given function. * @method $this roundYears(float $precision = 1, string $function = "round") Round the current instance year with given precision using the given function. * @method $this floorYear(float $precision = 1) Truncate the current instance year with given precision. diff --git a/src/Carbon/CarbonImmutable.php b/src/Carbon/CarbonImmutable.php index ff0c87aa40..ee8cb1559c 100644 --- a/src/Carbon/CarbonImmutable.php +++ b/src/Carbon/CarbonImmutable.php @@ -506,81 +506,96 @@ * @method CarbonImmutable addWeekday() Add one weekday to the instance (using date interval). * @method CarbonImmutable subWeekdays(int|float $value = 1) Sub weekdays (the $value count passed in) to the instance (using date interval). * @method CarbonImmutable subWeekday() Sub one weekday to the instance (using date interval). - * @method CarbonImmutable addRealMicros(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealMicro() Add one microsecond to the instance (using timestamp). - * @method CarbonImmutable subRealMicros(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealMicro() Sub one microsecond to the instance (using timestamp). + * @method CarbonImmutable addUTCMicros(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCMicro() Add one microsecond to the instance (using timestamp). + * @method CarbonImmutable subUTCMicros(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCMicro() Sub one microsecond to the instance (using timestamp). * @method CarbonPeriod microsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each microsecond or every X microseconds if a factor is given. - * @method CarbonImmutable addRealMicroseconds(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealMicrosecond() Add one microsecond to the instance (using timestamp). - * @method CarbonImmutable subRealMicroseconds(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealMicrosecond() Sub one microsecond to the instance (using timestamp). + * @method float diffInUTCMicros(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of microseconds. + * @method CarbonImmutable addUTCMicroseconds(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCMicrosecond() Add one microsecond to the instance (using timestamp). + * @method CarbonImmutable subUTCMicroseconds(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCMicrosecond() Sub one microsecond to the instance (using timestamp). * @method CarbonPeriod microsecondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each microsecond or every X microseconds if a factor is given. - * @method CarbonImmutable addRealMillis(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealMilli() Add one millisecond to the instance (using timestamp). - * @method CarbonImmutable subRealMillis(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealMilli() Sub one millisecond to the instance (using timestamp). + * @method float diffInUTCMicroseconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of microseconds. + * @method CarbonImmutable addUTCMillis(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCMilli() Add one millisecond to the instance (using timestamp). + * @method CarbonImmutable subUTCMillis(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCMilli() Sub one millisecond to the instance (using timestamp). * @method CarbonPeriod millisUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millisecond or every X milliseconds if a factor is given. - * @method CarbonImmutable addRealMilliseconds(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealMillisecond() Add one millisecond to the instance (using timestamp). - * @method CarbonImmutable subRealMilliseconds(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealMillisecond() Sub one millisecond to the instance (using timestamp). + * @method float diffInUTCMillis(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of milliseconds. + * @method CarbonImmutable addUTCMilliseconds(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCMillisecond() Add one millisecond to the instance (using timestamp). + * @method CarbonImmutable subUTCMilliseconds(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCMillisecond() Sub one millisecond to the instance (using timestamp). * @method CarbonPeriod millisecondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millisecond or every X milliseconds if a factor is given. - * @method CarbonImmutable addRealSeconds(int|float $value = 1) Add seconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealSecond() Add one second to the instance (using timestamp). - * @method CarbonImmutable subRealSeconds(int|float $value = 1) Sub seconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealSecond() Sub one second to the instance (using timestamp). + * @method float diffInUTCMilliseconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of milliseconds. + * @method CarbonImmutable addUTCSeconds(int|float $value = 1) Add seconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCSecond() Add one second to the instance (using timestamp). + * @method CarbonImmutable subUTCSeconds(int|float $value = 1) Sub seconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCSecond() Sub one second to the instance (using timestamp). * @method CarbonPeriod secondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each second or every X seconds if a factor is given. - * @method CarbonImmutable addRealMinutes(int|float $value = 1) Add minutes (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealMinute() Add one minute to the instance (using timestamp). - * @method CarbonImmutable subRealMinutes(int|float $value = 1) Sub minutes (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealMinute() Sub one minute to the instance (using timestamp). + * @method float diffInUTCSeconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of seconds. + * @method CarbonImmutable addUTCMinutes(int|float $value = 1) Add minutes (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCMinute() Add one minute to the instance (using timestamp). + * @method CarbonImmutable subUTCMinutes(int|float $value = 1) Sub minutes (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCMinute() Sub one minute to the instance (using timestamp). * @method CarbonPeriod minutesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each minute or every X minutes if a factor is given. - * @method CarbonImmutable addRealHours(int|float $value = 1) Add hours (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealHour() Add one hour to the instance (using timestamp). - * @method CarbonImmutable subRealHours(int|float $value = 1) Sub hours (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealHour() Sub one hour to the instance (using timestamp). + * @method float diffInUTCMinutes(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of minutes. + * @method CarbonImmutable addUTCHours(int|float $value = 1) Add hours (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCHour() Add one hour to the instance (using timestamp). + * @method CarbonImmutable subUTCHours(int|float $value = 1) Sub hours (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCHour() Sub one hour to the instance (using timestamp). * @method CarbonPeriod hoursUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each hour or every X hours if a factor is given. - * @method CarbonImmutable addRealDays(int|float $value = 1) Add days (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealDay() Add one day to the instance (using timestamp). - * @method CarbonImmutable subRealDays(int|float $value = 1) Sub days (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealDay() Sub one day to the instance (using timestamp). + * @method float diffInUTCHours(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of hours. + * @method CarbonImmutable addUTCDays(int|float $value = 1) Add days (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCDay() Add one day to the instance (using timestamp). + * @method CarbonImmutable subUTCDays(int|float $value = 1) Sub days (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCDay() Sub one day to the instance (using timestamp). * @method CarbonPeriod daysUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each day or every X days if a factor is given. - * @method CarbonImmutable addRealWeeks(int|float $value = 1) Add weeks (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealWeek() Add one week to the instance (using timestamp). - * @method CarbonImmutable subRealWeeks(int|float $value = 1) Sub weeks (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealWeek() Sub one week to the instance (using timestamp). + * @method float diffInUTCDays(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of days. + * @method CarbonImmutable addUTCWeeks(int|float $value = 1) Add weeks (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCWeek() Add one week to the instance (using timestamp). + * @method CarbonImmutable subUTCWeeks(int|float $value = 1) Sub weeks (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCWeek() Sub one week to the instance (using timestamp). * @method CarbonPeriod weeksUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each week or every X weeks if a factor is given. - * @method CarbonImmutable addRealMonths(int|float $value = 1) Add months (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealMonth() Add one month to the instance (using timestamp). - * @method CarbonImmutable subRealMonths(int|float $value = 1) Sub months (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealMonth() Sub one month to the instance (using timestamp). + * @method float diffInUTCWeeks(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of weeks. + * @method CarbonImmutable addUTCMonths(int|float $value = 1) Add months (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCMonth() Add one month to the instance (using timestamp). + * @method CarbonImmutable subUTCMonths(int|float $value = 1) Sub months (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCMonth() Sub one month to the instance (using timestamp). * @method CarbonPeriod monthsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each month or every X months if a factor is given. - * @method CarbonImmutable addRealQuarters(int|float $value = 1) Add quarters (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealQuarter() Add one quarter to the instance (using timestamp). - * @method CarbonImmutable subRealQuarters(int|float $value = 1) Sub quarters (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealQuarter() Sub one quarter to the instance (using timestamp). + * @method float diffInUTCMonths(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of months. + * @method CarbonImmutable addUTCQuarters(int|float $value = 1) Add quarters (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCQuarter() Add one quarter to the instance (using timestamp). + * @method CarbonImmutable subUTCQuarters(int|float $value = 1) Sub quarters (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCQuarter() Sub one quarter to the instance (using timestamp). * @method CarbonPeriod quartersUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each quarter or every X quarters if a factor is given. - * @method CarbonImmutable addRealYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealYear() Add one year to the instance (using timestamp). - * @method CarbonImmutable subRealYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealYear() Sub one year to the instance (using timestamp). + * @method float diffInUTCQuarters(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of quarters. + * @method CarbonImmutable addUTCYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCYear() Add one year to the instance (using timestamp). + * @method CarbonImmutable subUTCYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCYear() Sub one year to the instance (using timestamp). * @method CarbonPeriod yearsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each year or every X years if a factor is given. - * @method CarbonImmutable addRealDecades(int|float $value = 1) Add decades (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealDecade() Add one decade to the instance (using timestamp). - * @method CarbonImmutable subRealDecades(int|float $value = 1) Sub decades (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealDecade() Sub one decade to the instance (using timestamp). + * @method float diffInUTCYears(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of years. + * @method CarbonImmutable addUTCDecades(int|float $value = 1) Add decades (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCDecade() Add one decade to the instance (using timestamp). + * @method CarbonImmutable subUTCDecades(int|float $value = 1) Sub decades (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCDecade() Sub one decade to the instance (using timestamp). * @method CarbonPeriod decadesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each decade or every X decades if a factor is given. - * @method CarbonImmutable addRealCenturies(int|float $value = 1) Add centuries (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealCentury() Add one century to the instance (using timestamp). - * @method CarbonImmutable subRealCenturies(int|float $value = 1) Sub centuries (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealCentury() Sub one century to the instance (using timestamp). + * @method float diffInUTCDecades(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of decades. + * @method CarbonImmutable addUTCCenturies(int|float $value = 1) Add centuries (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCCentury() Add one century to the instance (using timestamp). + * @method CarbonImmutable subUTCCenturies(int|float $value = 1) Sub centuries (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCCentury() Sub one century to the instance (using timestamp). * @method CarbonPeriod centuriesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each century or every X centuries if a factor is given. - * @method CarbonImmutable addRealMillennia(int|float $value = 1) Add millennia (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable addRealMillennium() Add one millennium to the instance (using timestamp). - * @method CarbonImmutable subRealMillennia(int|float $value = 1) Sub millennia (the $value count passed in) to the instance (using timestamp). - * @method CarbonImmutable subRealMillennium() Sub one millennium to the instance (using timestamp). + * @method float diffInUTCCenturies(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of centuries. + * @method CarbonImmutable addUTCMillennia(int|float $value = 1) Add millennia (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable addUTCMillennium() Add one millennium to the instance (using timestamp). + * @method CarbonImmutable subUTCMillennia(int|float $value = 1) Sub millennia (the $value count passed in) to the instance (using timestamp). + * @method CarbonImmutable subUTCMillennium() Sub one millennium to the instance (using timestamp). * @method CarbonPeriod millenniaUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millennium or every X millennia if a factor is given. + * @method float diffInUTCMillennia(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of millennia. * @method CarbonImmutable roundYear(float $precision = 1, string $function = "round") Round the current instance year with given precision using the given function. * @method CarbonImmutable roundYears(float $precision = 1, string $function = "round") Round the current instance year with given precision using the given function. * @method CarbonImmutable floorYear(float $precision = 1) Truncate the current instance year with given precision. diff --git a/src/Carbon/CarbonInterface.php b/src/Carbon/CarbonInterface.php index f24311c463..2399260415 100644 --- a/src/Carbon/CarbonInterface.php +++ b/src/Carbon/CarbonInterface.php @@ -522,81 +522,96 @@ * @method CarbonInterface addWeekday() Add one weekday to the instance (using date interval). * @method CarbonInterface subWeekdays(int|float $value = 1) Sub weekdays (the $value count passed in) to the instance (using date interval). * @method CarbonInterface subWeekday() Sub one weekday to the instance (using date interval). - * @method CarbonInterface addRealMicros(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMicro() Add one microsecond to the instance (using timestamp). - * @method CarbonInterface subRealMicros(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMicro() Sub one microsecond to the instance (using timestamp). + * @method CarbonInterface addUTCMicros(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMicro() Add one microsecond to the instance (using timestamp). + * @method CarbonInterface subUTCMicros(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMicro() Sub one microsecond to the instance (using timestamp). * @method CarbonPeriod microsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each microsecond or every X microseconds if a factor is given. - * @method CarbonInterface addRealMicroseconds(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMicrosecond() Add one microsecond to the instance (using timestamp). - * @method CarbonInterface subRealMicroseconds(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMicrosecond() Sub one microsecond to the instance (using timestamp). + * @method float diffInUTCMicros(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of microseconds. + * @method CarbonInterface addUTCMicroseconds(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMicrosecond() Add one microsecond to the instance (using timestamp). + * @method CarbonInterface subUTCMicroseconds(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMicrosecond() Sub one microsecond to the instance (using timestamp). * @method CarbonPeriod microsecondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each microsecond or every X microseconds if a factor is given. - * @method CarbonInterface addRealMillis(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMilli() Add one millisecond to the instance (using timestamp). - * @method CarbonInterface subRealMillis(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMilli() Sub one millisecond to the instance (using timestamp). + * @method float diffInUTCMicroseconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of microseconds. + * @method CarbonInterface addUTCMillis(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMilli() Add one millisecond to the instance (using timestamp). + * @method CarbonInterface subUTCMillis(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMilli() Sub one millisecond to the instance (using timestamp). * @method CarbonPeriod millisUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millisecond or every X milliseconds if a factor is given. - * @method CarbonInterface addRealMilliseconds(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMillisecond() Add one millisecond to the instance (using timestamp). - * @method CarbonInterface subRealMilliseconds(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMillisecond() Sub one millisecond to the instance (using timestamp). + * @method float diffInUTCMillis(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of milliseconds. + * @method CarbonInterface addUTCMilliseconds(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMillisecond() Add one millisecond to the instance (using timestamp). + * @method CarbonInterface subUTCMilliseconds(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMillisecond() Sub one millisecond to the instance (using timestamp). * @method CarbonPeriod millisecondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millisecond or every X milliseconds if a factor is given. - * @method CarbonInterface addRealSeconds(int|float $value = 1) Add seconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealSecond() Add one second to the instance (using timestamp). - * @method CarbonInterface subRealSeconds(int|float $value = 1) Sub seconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealSecond() Sub one second to the instance (using timestamp). + * @method float diffInUTCMilliseconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of milliseconds. + * @method CarbonInterface addUTCSeconds(int|float $value = 1) Add seconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCSecond() Add one second to the instance (using timestamp). + * @method CarbonInterface subUTCSeconds(int|float $value = 1) Sub seconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCSecond() Sub one second to the instance (using timestamp). * @method CarbonPeriod secondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each second or every X seconds if a factor is given. - * @method CarbonInterface addRealMinutes(int|float $value = 1) Add minutes (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMinute() Add one minute to the instance (using timestamp). - * @method CarbonInterface subRealMinutes(int|float $value = 1) Sub minutes (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMinute() Sub one minute to the instance (using timestamp). + * @method float diffInUTCSeconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of seconds. + * @method CarbonInterface addUTCMinutes(int|float $value = 1) Add minutes (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMinute() Add one minute to the instance (using timestamp). + * @method CarbonInterface subUTCMinutes(int|float $value = 1) Sub minutes (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMinute() Sub one minute to the instance (using timestamp). * @method CarbonPeriod minutesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each minute or every X minutes if a factor is given. - * @method CarbonInterface addRealHours(int|float $value = 1) Add hours (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealHour() Add one hour to the instance (using timestamp). - * @method CarbonInterface subRealHours(int|float $value = 1) Sub hours (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealHour() Sub one hour to the instance (using timestamp). + * @method float diffInUTCMinutes(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of minutes. + * @method CarbonInterface addUTCHours(int|float $value = 1) Add hours (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCHour() Add one hour to the instance (using timestamp). + * @method CarbonInterface subUTCHours(int|float $value = 1) Sub hours (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCHour() Sub one hour to the instance (using timestamp). * @method CarbonPeriod hoursUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each hour or every X hours if a factor is given. - * @method CarbonInterface addRealDays(int|float $value = 1) Add days (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealDay() Add one day to the instance (using timestamp). - * @method CarbonInterface subRealDays(int|float $value = 1) Sub days (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealDay() Sub one day to the instance (using timestamp). + * @method float diffInUTCHours(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of hours. + * @method CarbonInterface addUTCDays(int|float $value = 1) Add days (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCDay() Add one day to the instance (using timestamp). + * @method CarbonInterface subUTCDays(int|float $value = 1) Sub days (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCDay() Sub one day to the instance (using timestamp). * @method CarbonPeriod daysUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each day or every X days if a factor is given. - * @method CarbonInterface addRealWeeks(int|float $value = 1) Add weeks (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealWeek() Add one week to the instance (using timestamp). - * @method CarbonInterface subRealWeeks(int|float $value = 1) Sub weeks (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealWeek() Sub one week to the instance (using timestamp). + * @method float diffInUTCDays(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of days. + * @method CarbonInterface addUTCWeeks(int|float $value = 1) Add weeks (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCWeek() Add one week to the instance (using timestamp). + * @method CarbonInterface subUTCWeeks(int|float $value = 1) Sub weeks (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCWeek() Sub one week to the instance (using timestamp). * @method CarbonPeriod weeksUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each week or every X weeks if a factor is given. - * @method CarbonInterface addRealMonths(int|float $value = 1) Add months (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMonth() Add one month to the instance (using timestamp). - * @method CarbonInterface subRealMonths(int|float $value = 1) Sub months (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMonth() Sub one month to the instance (using timestamp). + * @method float diffInUTCWeeks(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of weeks. + * @method CarbonInterface addUTCMonths(int|float $value = 1) Add months (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMonth() Add one month to the instance (using timestamp). + * @method CarbonInterface subUTCMonths(int|float $value = 1) Sub months (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMonth() Sub one month to the instance (using timestamp). * @method CarbonPeriod monthsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each month or every X months if a factor is given. - * @method CarbonInterface addRealQuarters(int|float $value = 1) Add quarters (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealQuarter() Add one quarter to the instance (using timestamp). - * @method CarbonInterface subRealQuarters(int|float $value = 1) Sub quarters (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealQuarter() Sub one quarter to the instance (using timestamp). + * @method float diffInUTCMonths(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of months. + * @method CarbonInterface addUTCQuarters(int|float $value = 1) Add quarters (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCQuarter() Add one quarter to the instance (using timestamp). + * @method CarbonInterface subUTCQuarters(int|float $value = 1) Sub quarters (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCQuarter() Sub one quarter to the instance (using timestamp). * @method CarbonPeriod quartersUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each quarter or every X quarters if a factor is given. - * @method CarbonInterface addRealYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealYear() Add one year to the instance (using timestamp). - * @method CarbonInterface subRealYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealYear() Sub one year to the instance (using timestamp). + * @method float diffInUTCQuarters(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of quarters. + * @method CarbonInterface addUTCYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCYear() Add one year to the instance (using timestamp). + * @method CarbonInterface subUTCYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCYear() Sub one year to the instance (using timestamp). * @method CarbonPeriod yearsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each year or every X years if a factor is given. - * @method CarbonInterface addRealDecades(int|float $value = 1) Add decades (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealDecade() Add one decade to the instance (using timestamp). - * @method CarbonInterface subRealDecades(int|float $value = 1) Sub decades (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealDecade() Sub one decade to the instance (using timestamp). + * @method float diffInUTCYears(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of years. + * @method CarbonInterface addUTCDecades(int|float $value = 1) Add decades (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCDecade() Add one decade to the instance (using timestamp). + * @method CarbonInterface subUTCDecades(int|float $value = 1) Sub decades (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCDecade() Sub one decade to the instance (using timestamp). * @method CarbonPeriod decadesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each decade or every X decades if a factor is given. - * @method CarbonInterface addRealCenturies(int|float $value = 1) Add centuries (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealCentury() Add one century to the instance (using timestamp). - * @method CarbonInterface subRealCenturies(int|float $value = 1) Sub centuries (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealCentury() Sub one century to the instance (using timestamp). + * @method float diffInUTCDecades(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of decades. + * @method CarbonInterface addUTCCenturies(int|float $value = 1) Add centuries (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCCentury() Add one century to the instance (using timestamp). + * @method CarbonInterface subUTCCenturies(int|float $value = 1) Sub centuries (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCCentury() Sub one century to the instance (using timestamp). * @method CarbonPeriod centuriesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each century or every X centuries if a factor is given. - * @method CarbonInterface addRealMillennia(int|float $value = 1) Add millennia (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMillennium() Add one millennium to the instance (using timestamp). - * @method CarbonInterface subRealMillennia(int|float $value = 1) Sub millennia (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMillennium() Sub one millennium to the instance (using timestamp). + * @method float diffInUTCCenturies(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of centuries. + * @method CarbonInterface addUTCMillennia(int|float $value = 1) Add millennia (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMillennium() Add one millennium to the instance (using timestamp). + * @method CarbonInterface subUTCMillennia(int|float $value = 1) Sub millennia (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMillennium() Sub one millennium to the instance (using timestamp). * @method CarbonPeriod millenniaUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millennium or every X millennia if a factor is given. + * @method float diffInUTCMillennia(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of millennia. * @method CarbonInterface roundYear(float $precision = 1, string $function = "round") Round the current instance year with given precision using the given function. * @method CarbonInterface roundYears(float $precision = 1, string $function = "round") Round the current instance year with given precision using the given function. * @method CarbonInterface floorYear(float $precision = 1) Truncate the current instance year with given precision. @@ -1075,6 +1090,8 @@ public function __toString(); public function add($unit, $value = 1, ?bool $overflow = null): static; /** + * @deprecated Prefer to use add addUTCUnit() which more accurately defines what it's doing. + * * Add seconds to the instance using timestamp. Positive $value travels * forward while negative $value travels into the past. * @@ -1085,6 +1102,17 @@ public function add($unit, $value = 1, ?bool $overflow = null): static; */ public function addRealUnit(string $unit, $value = 1): static; + /** + * Add seconds to the instance using timestamp. Positive $value travels + * forward while negative $value travels into the past. + * + * @param string $unit + * @param int|float|null $value + * + * @return static + */ + public function addUTCUnit(string $unit, $value = 1): static; + /** * Add given units to the current instance. */ @@ -4012,6 +4040,8 @@ public function startOfYear(); public function sub($unit, $value = 1, ?bool $overflow = null): static; /** + * @deprecated Prefer to use add subUTCUnit() which more accurately defines what it's doing. + * * Subtract seconds to the instance using timestamp. Positive $value travels * into the past while negative $value travels forward. * @@ -4022,6 +4052,17 @@ public function sub($unit, $value = 1, ?bool $overflow = null): static; */ public function subRealUnit($unit, $value = 1): static; + /** + * Subtract seconds to the instance using timestamp. Positive $value travels + * into the past while negative $value travels forward. + * + * @param string $unit + * @param int $value + * + * @return static + */ + public function subUTCUnit($unit, $value = 1): static; + /** * Subtract given units to the current instance. */ diff --git a/src/Carbon/Traits/Date.php b/src/Carbon/Traits/Date.php index 6738ace519..fdf06ca105 100644 --- a/src/Carbon/Traits/Date.php +++ b/src/Carbon/Traits/Date.php @@ -533,81 +533,96 @@ * @method CarbonInterface addWeekday() Add one weekday to the instance (using date interval). * @method CarbonInterface subWeekdays(int|float $value = 1) Sub weekdays (the $value count passed in) to the instance (using date interval). * @method CarbonInterface subWeekday() Sub one weekday to the instance (using date interval). - * @method CarbonInterface addRealMicros(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMicro() Add one microsecond to the instance (using timestamp). - * @method CarbonInterface subRealMicros(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMicro() Sub one microsecond to the instance (using timestamp). + * @method CarbonInterface addUTCMicros(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMicro() Add one microsecond to the instance (using timestamp). + * @method CarbonInterface subUTCMicros(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMicro() Sub one microsecond to the instance (using timestamp). * @method CarbonPeriod microsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each microsecond or every X microseconds if a factor is given. - * @method CarbonInterface addRealMicroseconds(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMicrosecond() Add one microsecond to the instance (using timestamp). - * @method CarbonInterface subRealMicroseconds(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMicrosecond() Sub one microsecond to the instance (using timestamp). + * @method float diffInUTCMicros(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of microseconds. + * @method CarbonInterface addUTCMicroseconds(int|float $value = 1) Add microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMicrosecond() Add one microsecond to the instance (using timestamp). + * @method CarbonInterface subUTCMicroseconds(int|float $value = 1) Sub microseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMicrosecond() Sub one microsecond to the instance (using timestamp). * @method CarbonPeriod microsecondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each microsecond or every X microseconds if a factor is given. - * @method CarbonInterface addRealMillis(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMilli() Add one millisecond to the instance (using timestamp). - * @method CarbonInterface subRealMillis(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMilli() Sub one millisecond to the instance (using timestamp). + * @method float diffInUTCMicroseconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of microseconds. + * @method CarbonInterface addUTCMillis(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMilli() Add one millisecond to the instance (using timestamp). + * @method CarbonInterface subUTCMillis(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMilli() Sub one millisecond to the instance (using timestamp). * @method CarbonPeriod millisUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millisecond or every X milliseconds if a factor is given. - * @method CarbonInterface addRealMilliseconds(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMillisecond() Add one millisecond to the instance (using timestamp). - * @method CarbonInterface subRealMilliseconds(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMillisecond() Sub one millisecond to the instance (using timestamp). + * @method float diffInUTCMillis(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of milliseconds. + * @method CarbonInterface addUTCMilliseconds(int|float $value = 1) Add milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMillisecond() Add one millisecond to the instance (using timestamp). + * @method CarbonInterface subUTCMilliseconds(int|float $value = 1) Sub milliseconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMillisecond() Sub one millisecond to the instance (using timestamp). * @method CarbonPeriod millisecondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millisecond or every X milliseconds if a factor is given. - * @method CarbonInterface addRealSeconds(int|float $value = 1) Add seconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealSecond() Add one second to the instance (using timestamp). - * @method CarbonInterface subRealSeconds(int|float $value = 1) Sub seconds (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealSecond() Sub one second to the instance (using timestamp). + * @method float diffInUTCMilliseconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of milliseconds. + * @method CarbonInterface addUTCSeconds(int|float $value = 1) Add seconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCSecond() Add one second to the instance (using timestamp). + * @method CarbonInterface subUTCSeconds(int|float $value = 1) Sub seconds (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCSecond() Sub one second to the instance (using timestamp). * @method CarbonPeriod secondsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each second or every X seconds if a factor is given. - * @method CarbonInterface addRealMinutes(int|float $value = 1) Add minutes (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMinute() Add one minute to the instance (using timestamp). - * @method CarbonInterface subRealMinutes(int|float $value = 1) Sub minutes (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMinute() Sub one minute to the instance (using timestamp). + * @method float diffInUTCSeconds(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of seconds. + * @method CarbonInterface addUTCMinutes(int|float $value = 1) Add minutes (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMinute() Add one minute to the instance (using timestamp). + * @method CarbonInterface subUTCMinutes(int|float $value = 1) Sub minutes (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMinute() Sub one minute to the instance (using timestamp). * @method CarbonPeriod minutesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each minute or every X minutes if a factor is given. - * @method CarbonInterface addRealHours(int|float $value = 1) Add hours (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealHour() Add one hour to the instance (using timestamp). - * @method CarbonInterface subRealHours(int|float $value = 1) Sub hours (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealHour() Sub one hour to the instance (using timestamp). + * @method float diffInUTCMinutes(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of minutes. + * @method CarbonInterface addUTCHours(int|float $value = 1) Add hours (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCHour() Add one hour to the instance (using timestamp). + * @method CarbonInterface subUTCHours(int|float $value = 1) Sub hours (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCHour() Sub one hour to the instance (using timestamp). * @method CarbonPeriod hoursUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each hour or every X hours if a factor is given. - * @method CarbonInterface addRealDays(int|float $value = 1) Add days (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealDay() Add one day to the instance (using timestamp). - * @method CarbonInterface subRealDays(int|float $value = 1) Sub days (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealDay() Sub one day to the instance (using timestamp). + * @method float diffInUTCHours(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of hours. + * @method CarbonInterface addUTCDays(int|float $value = 1) Add days (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCDay() Add one day to the instance (using timestamp). + * @method CarbonInterface subUTCDays(int|float $value = 1) Sub days (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCDay() Sub one day to the instance (using timestamp). * @method CarbonPeriod daysUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each day or every X days if a factor is given. - * @method CarbonInterface addRealWeeks(int|float $value = 1) Add weeks (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealWeek() Add one week to the instance (using timestamp). - * @method CarbonInterface subRealWeeks(int|float $value = 1) Sub weeks (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealWeek() Sub one week to the instance (using timestamp). + * @method float diffInUTCDays(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of days. + * @method CarbonInterface addUTCWeeks(int|float $value = 1) Add weeks (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCWeek() Add one week to the instance (using timestamp). + * @method CarbonInterface subUTCWeeks(int|float $value = 1) Sub weeks (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCWeek() Sub one week to the instance (using timestamp). * @method CarbonPeriod weeksUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each week or every X weeks if a factor is given. - * @method CarbonInterface addRealMonths(int|float $value = 1) Add months (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMonth() Add one month to the instance (using timestamp). - * @method CarbonInterface subRealMonths(int|float $value = 1) Sub months (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMonth() Sub one month to the instance (using timestamp). + * @method float diffInUTCWeeks(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of weeks. + * @method CarbonInterface addUTCMonths(int|float $value = 1) Add months (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMonth() Add one month to the instance (using timestamp). + * @method CarbonInterface subUTCMonths(int|float $value = 1) Sub months (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMonth() Sub one month to the instance (using timestamp). * @method CarbonPeriod monthsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each month or every X months if a factor is given. - * @method CarbonInterface addRealQuarters(int|float $value = 1) Add quarters (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealQuarter() Add one quarter to the instance (using timestamp). - * @method CarbonInterface subRealQuarters(int|float $value = 1) Sub quarters (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealQuarter() Sub one quarter to the instance (using timestamp). + * @method float diffInUTCMonths(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of months. + * @method CarbonInterface addUTCQuarters(int|float $value = 1) Add quarters (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCQuarter() Add one quarter to the instance (using timestamp). + * @method CarbonInterface subUTCQuarters(int|float $value = 1) Sub quarters (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCQuarter() Sub one quarter to the instance (using timestamp). * @method CarbonPeriod quartersUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each quarter or every X quarters if a factor is given. - * @method CarbonInterface addRealYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealYear() Add one year to the instance (using timestamp). - * @method CarbonInterface subRealYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealYear() Sub one year to the instance (using timestamp). + * @method float diffInUTCQuarters(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of quarters. + * @method CarbonInterface addUTCYears(int|float $value = 1) Add years (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCYear() Add one year to the instance (using timestamp). + * @method CarbonInterface subUTCYears(int|float $value = 1) Sub years (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCYear() Sub one year to the instance (using timestamp). * @method CarbonPeriod yearsUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each year or every X years if a factor is given. - * @method CarbonInterface addRealDecades(int|float $value = 1) Add decades (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealDecade() Add one decade to the instance (using timestamp). - * @method CarbonInterface subRealDecades(int|float $value = 1) Sub decades (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealDecade() Sub one decade to the instance (using timestamp). + * @method float diffInUTCYears(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of years. + * @method CarbonInterface addUTCDecades(int|float $value = 1) Add decades (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCDecade() Add one decade to the instance (using timestamp). + * @method CarbonInterface subUTCDecades(int|float $value = 1) Sub decades (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCDecade() Sub one decade to the instance (using timestamp). * @method CarbonPeriod decadesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each decade or every X decades if a factor is given. - * @method CarbonInterface addRealCenturies(int|float $value = 1) Add centuries (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealCentury() Add one century to the instance (using timestamp). - * @method CarbonInterface subRealCenturies(int|float $value = 1) Sub centuries (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealCentury() Sub one century to the instance (using timestamp). + * @method float diffInUTCDecades(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of decades. + * @method CarbonInterface addUTCCenturies(int|float $value = 1) Add centuries (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCCentury() Add one century to the instance (using timestamp). + * @method CarbonInterface subUTCCenturies(int|float $value = 1) Sub centuries (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCCentury() Sub one century to the instance (using timestamp). * @method CarbonPeriod centuriesUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each century or every X centuries if a factor is given. - * @method CarbonInterface addRealMillennia(int|float $value = 1) Add millennia (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface addRealMillennium() Add one millennium to the instance (using timestamp). - * @method CarbonInterface subRealMillennia(int|float $value = 1) Sub millennia (the $value count passed in) to the instance (using timestamp). - * @method CarbonInterface subRealMillennium() Sub one millennium to the instance (using timestamp). + * @method float diffInUTCCenturies(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of centuries. + * @method CarbonInterface addUTCMillennia(int|float $value = 1) Add millennia (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface addUTCMillennium() Add one millennium to the instance (using timestamp). + * @method CarbonInterface subUTCMillennia(int|float $value = 1) Sub millennia (the $value count passed in) to the instance (using timestamp). + * @method CarbonInterface subUTCMillennium() Sub one millennium to the instance (using timestamp). * @method CarbonPeriod millenniaUntil($endDate = null, int|float $factor = 1) Return an iterable period from current date to given end (string, DateTime or Carbon instance) for each millennium or every X millennia if a factor is given. + * @method float diffInUTCMillennia(DateTimeInterface|string|null $date, bool $absolute = false) Convert current and given date in UTC timezone and return a floating number of millennia. * @method CarbonInterface roundYear(float $precision = 1, string $function = "round") Round the current instance year with given precision using the given function. * @method CarbonInterface roundYears(float $precision = 1, string $function = "round") Round the current instance year with given precision using the given function. * @method CarbonInterface floorYear(float $precision = 1) Truncate the current instance year with given precision. @@ -2704,9 +2719,10 @@ public function __call(string $method, array $parameters): mixed if ($action === 'add' || $action === 'sub') { $unit = substr($unit, 3); + $utcUnit = $this->getUTCUnit($unit); - if (str_starts_with($unit, 'Real')) { - $unit = static::singularUnit(substr($unit, 4)); + if ($utcUnit) { + $unit = static::singularUnit($utcUnit); return $this->{"{$action}RealUnit"}($unit, ...$parameters); } @@ -2928,4 +2944,17 @@ private function callGetOrSet(string $name, mixed $value): mixed return $this->get($name); } + + private function getUTCUnit(string $unit): ?string + { + if (str_starts_with($unit, 'Real')) { + return substr($unit, 4); + } + + if (str_starts_with($unit, 'UTC')) { + return substr($unit, 3); + } + + return null; + } } diff --git a/tests/Carbon/IsTest.php b/tests/Carbon/IsTest.php index edf1f7ec36..cc57d7b70b 100644 --- a/tests/Carbon/IsTest.php +++ b/tests/Carbon/IsTest.php @@ -17,7 +17,6 @@ use Carbon\Carbon; use DateTime; use PHPUnit\Framework\Attributes\DataProvider; -use PHPUnit\Framework\Attributes\Group; use stdClass; use Tests\AbstractTestCase; use TypeError; @@ -610,7 +609,6 @@ public function testIsCurrentSecondFalse() $this->assertFalse(Carbon::now()->subDay()->isCurrentSecond()); } - #[Group('php-8.1')] public function testIsSameMicrosecond() { $current = new Carbon('2018-05-06T13:30:54.123456'); diff --git a/tests/Carbon/ModifyTest.php b/tests/Carbon/ModifyTest.php index 9e09e47119..ba5d8403f3 100644 --- a/tests/Carbon/ModifyTest.php +++ b/tests/Carbon/ModifyTest.php @@ -18,7 +18,6 @@ use Closure; use DateMalformedStringException; use InvalidArgumentException; -use PHPUnit\Framework\Attributes\Group; use Tests\AbstractTestCase; class ModifyTest extends AbstractTestCase @@ -31,7 +30,6 @@ public function testSimpleModify() $this->assertSame(24.0, $a->diffInHours($b)); } - #[Group('php-8.1')] public function testTimezoneModify() { $php81Fix = 1.0; @@ -50,7 +48,7 @@ public function testTimezoneModify() $a = new Carbon('2014-03-30 00:00:00', 'Europe/London'); $b = $a->copy(); - $b->addRealHours(24); + $b->addUTCHours(24); $this->assertSame(-24.0, $b->diffInHours($a, false)); $this->assertSame(-24.0 * 60, $b->diffInMinutes($a, false)); $this->assertSame(-24.0 * 60 * 60, $b->diffInSeconds($a, false)); @@ -117,6 +115,15 @@ public function testTimezoneModify() $this->assertSame(-24.0 * 60 * 60 * 1000, $b->diffInMilliseconds($a, false)); $this->assertSame(-24.0 * 60 * 60 * 1000000, $b->diffInMicroseconds($a, false)); + $a = new Carbon('2014-03-30 00:00:00', 'Europe/London'); + $b = $a->copy(); + $b->addUTCDay(); + $this->assertSame(-24.0, $b->diffInHours($a, false)); + $this->assertSame(-24.0 * 60, $b->diffInMinutes($a, false)); + $this->assertSame(-24.0 * 60 * 60, $b->diffInSeconds($a, false)); + $this->assertSame(-24.0 * 60 * 60 * 1000, $b->diffInMilliseconds($a, false)); + $this->assertSame(-24.0 * 60 * 60 * 1000000, $b->diffInMicroseconds($a, false)); + $a = new Carbon('2014-03-30 00:00:00', 'Europe/London'); $b = $a->copy(); $b->addRealWeeks(1 / 7); diff --git a/tests/CarbonImmutable/IsTest.php b/tests/CarbonImmutable/IsTest.php index 4d6ae185c2..9177548558 100644 --- a/tests/CarbonImmutable/IsTest.php +++ b/tests/CarbonImmutable/IsTest.php @@ -17,7 +17,6 @@ use DateTime; use InvalidArgumentException; use PHPUnit\Framework\Attributes\DataProvider; -use PHPUnit\Framework\Attributes\Group; use stdClass; use Tests\AbstractTestCase; use TypeError; @@ -640,7 +639,6 @@ public function testIsCurrentSecondFalse() $this->assertFalse(Carbon::now()->subDay()->isCurrentSecond()); } - #[Group('php-8.1')] public function testIsSameMicrosecond() { $current = new Carbon('2018-05-06T13:30:54.123456'); diff --git a/tests/CarbonImmutable/ModifyTest.php b/tests/CarbonImmutable/ModifyTest.php index 4ee081b816..b6dd4ebc01 100644 --- a/tests/CarbonImmutable/ModifyTest.php +++ b/tests/CarbonImmutable/ModifyTest.php @@ -14,7 +14,6 @@ namespace Tests\CarbonImmutable; use Carbon\CarbonImmutable as Carbon; -use PHPUnit\Framework\Attributes\Group; use Tests\AbstractTestCase; class ModifyTest extends AbstractTestCase @@ -33,7 +32,6 @@ public function testSimpleModifyWithNamedParameter() $this->assertSame(24.0, $a->diffInHours($b)); } - #[Group('php-8.1')] public function testTimezoneModify() { $php81Fix = 1.0; diff --git a/tests/CarbonInterval/AddTest.php b/tests/CarbonInterval/AddTest.php index 3a25291da6..071a5989a3 100644 --- a/tests/CarbonInterval/AddTest.php +++ b/tests/CarbonInterval/AddTest.php @@ -20,7 +20,6 @@ use DateTime; use DateTimeImmutable; use InvalidArgumentException; -use PHPUnit\Framework\Attributes\Group; use PHPUnit\Framework\Attributes\TestWith; use Tests\AbstractTestCase; use Tests\Carbon\Fixtures\MyCarbon; @@ -77,7 +76,6 @@ public function testAddWithNegativeDiffDateInterval() $this->assertCarbonInterval($ci, 4, 3, 28, 8, 10, 11); } - #[Group('php-8.1')] public function testAddMicroseconds() { $diff = Carbon::now()->diff(Carbon::now()->addDays(3)->addMicroseconds(111222));