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