Pionia Core

CarbonInterval extends DateInterval
in package
implements CarbonConverterInterface Uses LocalFactory, IntervalRounding, IntervalStep, MagicParameter, Mixin, Options, ToStringFormat

A simple API extension for DateInterval.

The implementation provides helpers to handle weeks but only days are saved. Weeks are calculated based on the total days of the current instance.

Table of Contents

Interfaces

CarbonConverterInterface

Constants

NEGATIVE  = -1
NO_LIMIT  = -1
Unlimited parts for forHumans() method.
PERIOD_DAYS  = 'D'
PERIOD_HOURS  = 'H'
PERIOD_MINUTES  = 'M'
PERIOD_MONTHS  = 'M'
PERIOD_PREFIX  = 'P'
Interval spec period designators
PERIOD_SECONDS  = 'S'
PERIOD_TIME_PREFIX  = 'T'
PERIOD_YEARS  = 'Y'
POSITIVE  = 1
SPECIAL_TRANSLATIONS  = [1 => ['option' => \Carbon\CarbonInterface::ONE_DAY_WORDS, 'future' => 'diff_tomorrow', 'past' => 'diff_yesterday'], 2 => ['option' => \Carbon\CarbonInterface::TWO_DAY_WORDS, 'future' => 'diff_after_tomorrow', 'past' => 'diff_before_yesterday']]

Properties

$daysExcludeWeeks  : int
$dayz  : int
$dayzExcludeWeeks  : int
$hours  : int
$locale  : string
$microExcludeMilli  : int
$microseconds  : int
$milliseconds  : int
$minutes  : int
$months  : int
$seconds  : int
$totalDays  : float
$totalDayz  : float
$totalHours  : float
$totalMicroseconds  : float
$totalMilliseconds  : float
$totalMinutes  : float
$totalMonths  : float
$totalSeconds  : float
$totalWeeks  : float
$totalYears  : float
$weeks  : int
$years  : int
$cascadeFactors  : array<string|int, mixed>|null
$endDate  : CarbonInterface|null
End date if interval was created from a difference between 2 dates.
$formats  : array<string|int, mixed>
$initialValues  : array<string|int, mixed>|null
$localFormatFunction  : string|callable|null
Function to call instead of format.
$localGenericMacros  : array<string|int, mixed>|null
Instance-specific generic macros.
$localHumanDiffOptions  : int|null
Options for diffForHumans and forHumans methods.
$localMacros  : array<string|int, mixed>|null
Instance-specific macros.
$localMonthsOverflow  : bool|null
Indicates if months should be calculated with overflow.
$localSerializer  : string|callable|null
Format to use on JSON serialization.
$localStrictModeEnabled  : bool|null
Indicates if the strict mode is in use.
$localToStringFormat  : string|callable|null
Format to use on string cast.
$localYearsOverflow  : bool|null
Indicates if years should be calculated with overflow.
$macroContextStack  : array<string|int, mixed>
Stack of macro instance contexts.
$macros  : array<string|int, mixed>
The registered macros.
$originalInput  : mixed
The input used to create the interval.
$rawInterval  : DateInterval|null
End date if interval was created from a difference between 2 dates.
$startDate  : CarbonInterface|null
Start date if interval was created from a difference between 2 dates.
$step  : Closure|null
Step to apply instead of a fixed interval to get the new date.
$timezoneSetting  : DateTimeZone|string|int|null
Timezone handler for settings() method.
$clock  : WrapperClock|null
The clock that generated the current instance (or FactoryImmutable::getDefaultInstance() if none)
$flipCascadeFactors  : array<string|int, mixed>|null
$floatSettersEnabled  : bool

Methods

__call()  : static|int|float|string
Allow fluent calls on the setters... CarbonInterval::years(3)->months(5)->day().
__callStatic()  : static|mixed|null
Provide static helpers to create instances. Allows CarbonInterval::years(3).
__construct()  : mixed
Create a new CarbonInterval instance.
__debugInfo()  : array<string|int, mixed>
Show truthy properties on var_dump().
__get()  : int|float|string|null
Get a part of the CarbonInterval object.
__set()  : mixed
Set a part of the CarbonInterval object.
__set_state()  : static
Evaluate the PHP generated by var_export() and recreate the exported CarbonInterval instance.
__toString()  : string
Format the instance as a string using the forHumans() function.
__unserialize()  : void
abs()  : $this
Invert the interval if it's inverted.
absolute()  : $this
add()  : $this
Add the passed interval to the current instance.
addDays()  : $this
addHours()  : $this
addMicroseconds()  : $this
addMilliseconds()  : $this
addMinutes()  : $this
addMonths()  : $this
addSeconds()  : $this
addWeeks()  : $this
addYears()  : $this
between()  : bool
Determines if the instance is between two others.
betweenExcluded()  : bool
Determines if the instance is between two others, bounds excluded.
betweenIncluded()  : bool
Determines if the instance is between two others, bounds excluded.
cascade()  : $this
Convert overflowed values into bigger units.
cast()  : T
Cast the current instance into the given class.
ceil()  : $this
Ceil the current instance second with given precision if specified.
ceilCenturies()  : $this
ceilCentury()  : $this
ceilDay()  : $this
ceilDays()  : $this
ceilDecade()  : $this
ceilDecades()  : $this
ceilHour()  : $this
ceilHours()  : $this
ceilMicrosecond()  : $this
ceilMicroseconds()  : $this
ceilMillennia()  : $this
ceilMillennium()  : $this
ceilMillisecond()  : $this
ceilMilliseconds()  : $this
ceilMinute()  : $this
ceilMinutes()  : $this
ceilMonth()  : $this
ceilMonths()  : $this
ceilQuarter()  : $this
ceilQuarters()  : $this
ceilSecond()  : $this
ceilSeconds()  : $this
ceilUnit()  : $this
Ceil the current instance at the given unit with given precision if specified.
ceilWeek()  : $this
ceilWeeks()  : $this
ceilYear()  : $this
ceilYears()  : $this
clone()  : static
Get a copy of the instance.
compare()  : int
Comparing with passed interval.
compareDateIntervals()  : int
Comparing 2 date intervals.
convertDate()  : CarbonInterface
Take a date and apply either the step if set, or the current interval else.
copy()  : static
Get a copy of the instance.
create()  : static
Create a new CarbonInterval instance from specific values.
createFromDateString()  : static
Sets up a DateInterval from the relative parts of the string.
createFromFormat()  : static
Parse a string into a new CarbonInterval object according to the specified format.
day()  : CarbonInterval
days()  : CarbonInterval
daysExcludeWeeks()  : CarbonInterval
dayz()  : CarbonInterval
dayzExcludeWeeks()  : CarbonInterval
diff()  : static
Create an interval from the difference between 2 dates.
divide()  : $this
Divide and cascade current instance by a given divider.
enableFloatSetters()  : void
This option allow you to opt-in for the Carbon 3 behavior where float values will no longer be cast to integer (so truncated).
end()  : CarbonInterface|null
Return the end date if interval was created from a difference between 2 dates.
eq()  : bool
Determines if the instance is equal to another
equalTo()  : bool
Determines if the instance is equal to another
floor()  : $this
Round the current instance second with given precision if specified.
floorCenturies()  : $this
floorCentury()  : $this
floorDay()  : $this
floorDays()  : $this
floorDecade()  : $this
floorDecades()  : $this
floorHour()  : $this
floorHours()  : $this
floorMicrosecond()  : $this
floorMicroseconds()  : $this
floorMillennia()  : $this
floorMillennium()  : $this
floorMillisecond()  : $this
floorMilliseconds()  : $this
floorMinute()  : $this
floorMinutes()  : $this
floorMonth()  : $this
floorMonths()  : $this
floorQuarter()  : $this
floorQuarters()  : $this
floorSecond()  : $this
floorSeconds()  : $this
floorUnit()  : $this
Truncate the current instance at the given unit with given precision if specified.
floorWeek()  : $this
floorWeeks()  : $this
floorYear()  : $this
floorYears()  : $this
forHumans()  : string
Get the current interval in a human readable format in the current locale.
format()  : string
fromString()  : static
Creates a CarbonInterval from string.
get()  : int|float|string|null
Get a part of the CarbonInterval object.
getCascadeFactors()  : array<string|int, mixed>
Mapping of units and factors for cascading.
getClock()  : WrapperClock|null
getDateIntervalSpec()  : string
Get the interval_spec string of a date interval.
getDaysPerWeek()  : int|float
Returns current config for days per week.
getFactor()  : int|float|null
Returns the factor for a given source-to-target couple.
getFactorWithDefault()  : int|float|null
Returns the factor for a given source-to-target couple if set, else try to find the appropriate constant as the factor, such as Carbon::DAYS_PER_WEEK.
getHoursPerDay()  : int|float
Returns current config for hours per day.
getMicrosecondsPerMillisecond()  : int|float
Returns current config for microseconds per second.
getMillisecondsPerSecond()  : int|float
Returns current config for microseconds per second.
getMinutesPerHour()  : int|float
Returns current config for minutes per hour.
getNonZeroValues()  : array<string|int, int>
Returns interval non-zero values as an array where key are the unit names and values the counts.
getSecondsPerMinute()  : int|float
Returns current config for seconds per minute.
getSettings()  : array<string|int, mixed>
Returns current local settings.
getStep()  : Closure
Get the dynamic step in use.
getValuesSequence()  : array<string|int, int>
Returns interval values as an array where key are the unit names and values the counts from the biggest non-zero one the the smallest non-zero one.
greaterThan()  : bool
Determines if the instance is greater (longer) than another
greaterThanOrEqualTo()  : bool
Determines if the instance is greater (longer) than or equal to another
gt()  : bool
Determines if the instance is greater (longer) than another
gte()  : bool
Determines if the instance is greater (longer) than or equal to another
hasMacro()  : bool
Check if macro is registered.
hasNegativeValues()  : bool
hasPositiveValues()  : bool
hour()  : CarbonInterval
hours()  : CarbonInterval
instance()  : static
Create a CarbonInterval instance from a DateInterval one. Can not instance DateInterval objects created from DateTime::diff() as you can't externally set the $days field.
invert()  : $this
Invert the interval.
isBetween()  : bool
Determines if the instance is between two others
isEmpty()  : bool
Returns true if the interval is empty for each unit.
lessThan()  : bool
Determines if the instance is less (shorter) than another
lessThanOrEqualTo()  : bool
Determines if the instance is less (shorter) than or equal to another
lt()  : bool
Determines if the instance is less (shorter) than another
lte()  : bool
Determines if the instance is less (shorter) than or equal to another
macro()  : void
Register a custom macro.
make()  : static|null
Make a CarbonInterval instance from given variable if possible.
microsecond()  : CarbonInterval
microseconds()  : CarbonInterval
millisecond()  : CarbonInterval
milliseconds()  : CarbonInterval
minus()  : $this
Add given parameters to the current interval.
minute()  : CarbonInterval
minutes()  : CarbonInterval
mixin()  : void
Register macros from a mixin object.
month()  : CarbonInterval
months()  : CarbonInterval
multiply()  : $this
Multiply and cascade current instance by a given factor.
ne()  : bool
Determines if the instance is not equal to another
notEqualTo()  : bool
Determines if the instance is not equal to another
optimize()  : $this
Get rid of the original input, start date and end date that may be kept in memory.
original()  : array<string|int, mixed>|int|string|DateInterval|mixed|null
Return the original source used to create the current interval.
parseFromLocale()  : static
Creates a CarbonInterval from string using a different locale.
plus()  : $this
Add given parameters to the current interval.
resetToStringFormat()  : void
Reset the format used to the default when type juggling a Carbon instance to a string
round()  : $this
Round the current instance second with given precision if specified.
roundCenturies()  : $this
roundCentury()  : $this
roundDay()  : $this
roundDays()  : $this
roundDecade()  : $this
roundDecades()  : $this
roundHour()  : $this
roundHours()  : $this
roundMicrosecond()  : $this
roundMicroseconds()  : $this
roundMillennia()  : $this
roundMillennium()  : $this
roundMillisecond()  : $this
roundMilliseconds()  : $this
roundMinute()  : $this
roundMinutes()  : $this
roundMonth()  : $this
roundMonths()  : $this
roundQuarter()  : $this
roundQuarters()  : $this
roundSecond()  : $this
roundSeconds()  : $this
roundUnit()  : static
Round the current instance at the given unit with given precision if specified and the given function.
roundWeek()  : $this
roundWeeks()  : $this
roundYear()  : $this
roundYears()  : $this
second()  : CarbonInterval
seconds()  : CarbonInterval
set()  : $this
Set a part of the CarbonInterval object.
setCascadeFactors()  : mixed
Set default cascading factors for ->cascade() method.
setStep()  : void
Set a step to apply instead of a fixed interval to get the new date.
setTimezone()  : static
Set the instance's timezone from a string or object.
settings()  : $this|static
Set specific options.
setToStringFormat()  : void
shares()  : $this
Divide current instance by a given divider. shares() is naive, it divides each unit separately and the result is rounded for each unit. So 5 hours and 20 minutes shared by 3 becomes 2 hours and 7 minutes.
shiftTimezone()  : static
Set the instance's timezone from a string or object and add/subtract the offset difference.
spec()  : string
Get the interval_spec string.
start()  : CarbonInterface|null
Return the start date if interval was created from a difference between 2 dates.
stepBy()  : CarbonPeriod
Decompose the current interval into
sub()  : $this
Subtract the passed interval to the current instance.
subDays()  : $this
subHours()  : $this
subMicroseconds()  : $this
subMilliseconds()  : $this
subMinutes()  : $this
subMonths()  : $this
subSeconds()  : $this
subtract()  : $this
Subtract the passed interval to the current instance.
subWeeks()  : $this
subYears()  : $this
times()  : $this
Multiply current instance given number of times. times() is naive, it multiplies each unit (so day can be greater than 31, hour can be greater than 23, etc.) and the result is rounded separately for each unit.
toArray()  : array<string|int, int>
Returns interval values as an array where key are the unit names and values the counts.
toDateInterval()  : DateInterval
Return native DateInterval PHP object matching the current instance.
toPeriod()  : CarbonPeriod
Convert the interval to a CarbonPeriod.
total()  : float
Get amount of given unit equivalent to the interval.
week()  : CarbonInterval
weeks()  : CarbonInterval
weeksAndDays()  : static
Allow setting of weeks and days to be cumulative.
year()  : CarbonInterval
years()  : CarbonInterval
addExtraDebugInfos()  : void
bindMacroContext()  : mixed
Stack a Carbon context from inside calls of self::this() and execute a given action.
callMacro()  : mixed
Call given macro.
callRoundMethod()  : static|null
context()  : static|null
Return the current context from inside a macro callee or a null if static.
copyProperties()  : static
getDefaultCascadeFactors()  : array<string|int, mixed>
getForHumansInitialVariables()  : array<string|int, mixed>
getForHumansParameters()  : array<string|int, mixed>
getRoundingMethodFromOptions()  : string|null
isLocalStrictModeEnabled()  : bool
makeFromString()  : self|null
resolveInterval()  : self|null
roundWith()  : static|null
solveNegativeInterval()  : static
this()  : static
Return the current context from inside a macro callee or a new one if static.
assertSafeForInteger()  : void
Throw an exception if precision loss when storing the given value as an integer would be >= 1.0.
castIntervalToClass()  : T
checkIntegerValue()  : void
checkStartAndEnd()  : void
copyNegativeUnits()  : void
copyStep()  : void
doCascade()  : static
getAnonymousClassCodeForTrait()  : string
getFactory()  : Factory
getFlipCascadeFactors()  : array<string|int, mixed>
getInnerValues()  : array<string|int, mixed>
getMagicParameter()  : mixed
getMixableMethods()  : Generator
handleDecimalPart()  : void
initLocalFactory()  : void
invertCascade()  : static
loadMixinClass()  : void
loadMixinTrait()  : void
needsDeclension()  : bool
resolveCarbon()  : Carbon|CarbonImmutable
Convert DateTimeImmutable instance to CarbonImmutable instance and DateTime instance to Carbon instance.
setSetting()  : $this
standardizeUnit()  : string
transmitFactory()  : T
Trigger the given action using the local factory of the object, so it will be transmitted to any object also using this trait and calling initLocalFactory() in its constructor.
withOriginal()  : T

Constants

NO_LIMIT

Unlimited parts for forHumans() method.

public mixed NO_LIMIT = -1

INF constant can be used instead.

PERIOD_PREFIX

Interval spec period designators

public mixed PERIOD_PREFIX = 'P'

SPECIAL_TRANSLATIONS

public mixed SPECIAL_TRANSLATIONS = [1 => ['option' => \Carbon\CarbonInterface::ONE_DAY_WORDS, 'future' => 'diff_tomorrow', 'past' => 'diff_yesterday'], 2 => ['option' => \Carbon\CarbonInterface::TWO_DAY_WORDS, 'future' => 'diff_after_tomorrow', 'past' => 'diff_before_yesterday']]

Properties

$daysExcludeWeeks

public int $daysExcludeWeeks

alias of dayzExcludeWeeks

$dayz

public int $dayz

Total days of the current interval (weeks * 7 + days).

$dayzExcludeWeeks

public int $dayzExcludeWeeks

Total days remaining in the final week of the current instance (days % 7).

$locale read-only

public string $locale

locale of the current instance

$microExcludeMilli

public int $microExcludeMilli

Remaining microseconds without the milliseconds.

$microseconds

public int $microseconds

Total microseconds of the current interval.

$milliseconds

public int $milliseconds

Total milliseconds of the current interval.

$minutes

public int $minutes

Total minutes of the current interval.

$seconds

public int $seconds

Total seconds of the current interval.

$totalDays read-only

public float $totalDays

Number of days equivalent to the interval.

$totalDayz read-only

public float $totalDayz

Alias for totalDays.

$totalHours read-only

public float $totalHours

Number of hours equivalent to the interval.

$totalMicroseconds read-only

public float $totalMicroseconds

Number of microseconds equivalent to the interval.

$totalMilliseconds read-only

public float $totalMilliseconds

Number of milliseconds equivalent to the interval.

$totalMinutes read-only

public float $totalMinutes

Number of minutes equivalent to the interval.

$totalMonths read-only

public float $totalMonths

Number of months equivalent to the interval.

$totalSeconds read-only

public float $totalSeconds

Number of seconds equivalent to the interval.

$totalWeeks read-only

public float $totalWeeks

Number of weeks equivalent to the interval.

$totalYears read-only

public float $totalYears

Number of years equivalent to the interval.

$weeks

public int $weeks

Total weeks of the current interval calculated from the days.

$cascadeFactors

protected static array<string|int, mixed>|null $cascadeFactors = null

$formats

protected static array<string|int, mixed> $formats = ['y' => 'y', 'Y' => 'y', 'o' => 'y', 'm' => 'm', 'n' => 'm', 'W' => 'weeks', 'd' => 'd', 'j' => 'd', 'z' => 'd', 'h' => 'h', 'g' => 'h', 'H' => 'h', 'G' => 'h', 'i' => 'i', 's' => 's', 'u' => 'micro', 'v' => 'milli']

$initialValues

protected array<string|int, mixed>|null $initialValues = null

$localFormatFunction

Function to call instead of format.

protected string|callable|null $localFormatFunction = null

$localGenericMacros

Instance-specific generic macros.

protected array<string|int, mixed>|null $localGenericMacros = null

$localHumanDiffOptions

Options for diffForHumans and forHumans methods.

protected int|null $localHumanDiffOptions = null

$localMacros

Instance-specific macros.

protected array<string|int, mixed>|null $localMacros = null

$localMonthsOverflow

Indicates if months should be calculated with overflow.

protected bool|null $localMonthsOverflow = null

Specific setting.

$localSerializer

Format to use on JSON serialization.

protected string|callable|null $localSerializer = null

$localStrictModeEnabled

Indicates if the strict mode is in use.

protected bool|null $localStrictModeEnabled = null

Specific setting.

$localToStringFormat

Format to use on string cast.

protected string|callable|null $localToStringFormat = null

$localYearsOverflow

Indicates if years should be calculated with overflow.

protected bool|null $localYearsOverflow = null

Specific setting.

$macroContextStack

Stack of macro instance contexts.

protected static array<string|int, mixed> $macroContextStack = []

$macros

The registered macros.

protected static array<string|int, mixed> $macros = []

$originalInput

The input used to create the interval.

protected mixed $originalInput = null

$rawInterval

End date if interval was created from a difference between 2 dates.

protected DateInterval|null $rawInterval = null

$step

Step to apply instead of a fixed interval to get the new date.

protected Closure|null $step

$timezoneSetting

Timezone handler for settings() method.

protected DateTimeZone|string|int|null $timezoneSetting = null

$clock

The clock that generated the current instance (or FactoryImmutable::getDefaultInstance() if none)

private WrapperClock|null $clock = null

$flipCascadeFactors

private static array<string|int, mixed>|null $flipCascadeFactors = null

$floatSettersEnabled

private static bool $floatSettersEnabled = false

Methods

__call()

Allow fluent calls on the setters... CarbonInterval::years(3)->months(5)->day().

public __call(string $method, array<string|int, mixed> $parameters) : static|int|float|string

Note: This is done using the magic method to allow static and instance methods to have the same names.

Parameters
$method : string

magic method name called

$parameters : array<string|int, mixed>

parameters list

Tags
throws
BadFluentSetterException|Throwable
Return values
static|int|float|string

__callStatic()

Provide static helpers to create instances. Allows CarbonInterval::years(3).

public static __callStatic(string $method, array<string|int, mixed> $parameters) : static|mixed|null

Note: This is done using the magic method to allow static and instance methods to have the same names.

Parameters
$method : string

magic method name called

$parameters : array<string|int, mixed>

parameters list

Return values
static|mixed|null

__construct()

Create a new CarbonInterval instance.

public __construct([Closure|DateInterval|string|int|null $years = null ][, int|float|null $months = null ][, int|float|null $weeks = null ][, int|float|null $days = null ][, int|float|null $hours = null ][, int|float|null $minutes = null ][, int|float|null $seconds = null ][, int|float|null $microseconds = null ]) : mixed
Parameters
$years : Closure|DateInterval|string|int|null = null
$months : int|float|null = null
$weeks : int|float|null = null
$days : int|float|null = null
$hours : int|float|null = null
$minutes : int|float|null = null
$seconds : int|float|null = null
$microseconds : int|float|null = null
Tags
throws
Exception

when the interval_spec (passed as $years) cannot be parsed as an interval.

__debugInfo()

Show truthy properties on var_dump().

public __debugInfo() : array<string|int, mixed>
Return values
array<string|int, mixed>

__get()

Get a part of the CarbonInterval object.

public __get(string $name) : int|float|string|null
Parameters
$name : string
Return values
int|float|string|null

__set_state()

Evaluate the PHP generated by var_export() and recreate the exported CarbonInterval instance.

public static __set_state(array<string|int, mixed> $dump) : static
Parameters
$dump : array<string|int, mixed>

data as exported by var_export()

Return values
static

__toString()

Format the instance as a string using the forHumans() function.

public __toString() : string
Tags
throws
Exception
Return values
string

__unserialize()

public __unserialize(array<string|int, mixed> $data) : void
Parameters
$data : array<string|int, mixed>

abs()

Invert the interval if it's inverted.

public abs([bool $absolute = false ]) : $this
Parameters
$absolute : bool = false

do nothing if set to false

Return values
$this

absolute()

public absolute([bool $absolute = true ]) : $this
Parameters
$absolute : bool = true

do nothing if set to false

Tags
alias

abs

Invert the interval if it's inverted.

Return values
$this

add()

Add the passed interval to the current instance.

public add(string|DateInterval $unit[, int|float $value = 1 ]) : $this
Parameters
$unit : string|DateInterval
$value : int|float = 1
Return values
$this

addDays()

public addDays(int|float $days) : $this

Add given number of days to the current interval

Parameters
$days : int|float
Return values
$this

addHours()

public addHours(int|float $hours) : $this

Add given number of hours to the current interval

Parameters
$hours : int|float
Return values
$this

addMicroseconds()

public addMicroseconds(int|float $microseconds) : $this

Add given number of microseconds to the current interval

Parameters
$microseconds : int|float
Return values
$this

addMilliseconds()

public addMilliseconds(int|float $milliseconds) : $this

Add given number of milliseconds to the current interval

Parameters
$milliseconds : int|float
Return values
$this

addMinutes()

public addMinutes(int|float $minutes) : $this

Add given number of minutes to the current interval

Parameters
$minutes : int|float
Return values
$this

addMonths()

public addMonths(int $months) : $this

Add given number of months to the current interval

Parameters
$months : int
Return values
$this

addSeconds()

public addSeconds(int|float $seconds) : $this

Add given number of seconds to the current interval

Parameters
$seconds : int|float
Return values
$this

addWeeks()

public addWeeks(int|float $weeks) : $this

Add given number of weeks to the current interval

Parameters
$weeks : int|float
Return values
$this

addYears()

public addYears(int $years) : $this

Add given number of years to the current interval

Parameters
$years : int
Return values
$this

between()

Determines if the instance is between two others.

public between(CarbonInterval|DateInterval|mixed $interval1, CarbonInterval|DateInterval|mixed $interval2[, bool $equal = true ]) : bool

The third argument allow you to specify if bounds are included or not (true by default) but for when you including/excluding bounds may produce different results in your application, we recommend to use the explicit methods ->betweenIncluded() or ->betweenExcluded() instead.

Parameters
$interval1 : CarbonInterval|DateInterval|mixed
$interval2 : CarbonInterval|DateInterval|mixed
$equal : bool = true

Indicates if an equal to comparison should be done

Tags
example 
CarbonInterval::hours(48)->between(CarbonInterval::day(), CarbonInterval::days(3)); // true
CarbonInterval::hours(48)->between(CarbonInterval::day(), CarbonInterval::hours(36)); // false
CarbonInterval::hours(48)->between(CarbonInterval::day(), CarbonInterval::days(2)); // true
CarbonInterval::hours(48)->between(CarbonInterval::day(), CarbonInterval::days(2), false); // false
Return values
bool

betweenExcluded()

Determines if the instance is between two others, bounds excluded.

public betweenExcluded(CarbonInterval|DateInterval|mixed $interval1, CarbonInterval|DateInterval|mixed $interval2) : bool
Parameters
$interval1 : CarbonInterval|DateInterval|mixed
$interval2 : CarbonInterval|DateInterval|mixed
Tags
example 
CarbonInterval::hours(48)->betweenExcluded(CarbonInterval::day(), CarbonInterval::days(3)); // true
CarbonInterval::hours(48)->betweenExcluded(CarbonInterval::day(), CarbonInterval::hours(36)); // false
CarbonInterval::hours(48)->betweenExcluded(CarbonInterval::day(), CarbonInterval::days(2)); // false
Return values
bool

betweenIncluded()

Determines if the instance is between two others, bounds excluded.

public betweenIncluded(CarbonInterval|DateInterval|mixed $interval1, CarbonInterval|DateInterval|mixed $interval2) : bool
Parameters
$interval1 : CarbonInterval|DateInterval|mixed
$interval2 : CarbonInterval|DateInterval|mixed
Tags
example 
CarbonInterval::hours(48)->betweenExcluded(CarbonInterval::day(), CarbonInterval::days(3)); // true
CarbonInterval::hours(48)->betweenExcluded(CarbonInterval::day(), CarbonInterval::hours(36)); // false
CarbonInterval::hours(48)->betweenExcluded(CarbonInterval::day(), CarbonInterval::days(2)); // true
Return values
bool

cascade()

Convert overflowed values into bigger units.

public cascade() : $this
Return values
$this

cast()

Cast the current instance into the given class.

public cast(string $className) : T
Parameters
$className : string
Tags
template

T of DateInterval

psalm-param

class-string<T> $className The $className::instance() method will be called to cast the current object.

Return values
T

ceil()

Ceil the current instance second with given precision if specified.

public ceil([DateInterval|string|float|int $precision = 1 ]) : $this
Parameters
$precision : DateInterval|string|float|int = 1
Tags
throws
Exception
Return values
$this

ceilCenturies()

public ceilCenturies(int|float $precision = 1) : $this

Ceil the current instance century with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilCentury()

public ceilCentury(int|float $precision = 1) : $this

Ceil the current instance century with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilDay()

public ceilDay(int|float $precision = 1) : $this

Ceil the current instance day with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilDays()

public ceilDays(int|float $precision = 1) : $this

Ceil the current instance day with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilDecade()

public ceilDecade(int|float $precision = 1) : $this

Ceil the current instance decade with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilDecades()

public ceilDecades(int|float $precision = 1) : $this

Ceil the current instance decade with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilHour()

public ceilHour(int|float $precision = 1) : $this

Ceil the current instance hour with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilHours()

public ceilHours(int|float $precision = 1) : $this

Ceil the current instance hour with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilMicrosecond()

public ceilMicrosecond(int|float $precision = 1) : $this

Ceil the current instance microsecond with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilMicroseconds()

public ceilMicroseconds(int|float $precision = 1) : $this

Ceil the current instance microsecond with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilMillennia()

public ceilMillennia(int|float $precision = 1) : $this

Ceil the current instance millennium with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilMillennium()

public ceilMillennium(int|float $precision = 1) : $this

Ceil the current instance millennium with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilMillisecond()

public ceilMillisecond(int|float $precision = 1) : $this

Ceil the current instance millisecond with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilMilliseconds()

public ceilMilliseconds(int|float $precision = 1) : $this

Ceil the current instance millisecond with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilMinute()

public ceilMinute(int|float $precision = 1) : $this

Ceil the current instance minute with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilMinutes()

public ceilMinutes(int|float $precision = 1) : $this

Ceil the current instance minute with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilMonth()

public ceilMonth(int|float $precision = 1) : $this

Ceil the current instance month with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilMonths()

public ceilMonths(int|float $precision = 1) : $this

Ceil the current instance month with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilQuarter()

public ceilQuarter(int|float $precision = 1) : $this

Ceil the current instance quarter with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilQuarters()

public ceilQuarters(int|float $precision = 1) : $this

Ceil the current instance quarter with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilSecond()

public ceilSecond(int|float $precision = 1) : $this

Ceil the current instance second with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilSeconds()

public ceilSeconds(int|float $precision = 1) : $this

Ceil the current instance second with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilUnit()

Ceil the current instance at the given unit with given precision if specified.

public ceilUnit(string $unit[, float|int|string|DateInterval|null $precision = 1 ]) : $this
Parameters
$unit : string
$precision : float|int|string|DateInterval|null = 1
Tags
throws
Exception
Return values
$this

ceilWeek()

public ceilWeek(int|float $precision = 1) : $this

Ceil the current instance day with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilWeeks()

public ceilWeeks(int|float $precision = 1) : $this

Ceil the current instance day with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilYear()

public ceilYear(int|float $precision = 1) : $this

Ceil the current instance year with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

ceilYears()

public ceilYears(int|float $precision = 1) : $this

Ceil the current instance year with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

clone()

Get a copy of the instance.

public clone() : static
Return values
static

compare()

Comparing with passed interval.

public compare(DateInterval $interval) : int
Parameters
$interval : DateInterval
Return values
int —

0, 1 or -1

compareDateIntervals()

Comparing 2 date intervals.

public static compareDateIntervals(DateInterval $first, DateInterval $second) : int
Parameters
$first : DateInterval
$second : DateInterval
Return values
int —

0, 1 or -1

convertDate()

Take a date and apply either the step if set, or the current interval else.

public convertDate(DateTimeInterface $dateTime[, bool $negated = false ]) : CarbonInterface

The interval/step is applied negatively (typically subtraction instead of addition) if $negated is true.

Parameters
$dateTime : DateTimeInterface
$negated : bool = false
Return values
CarbonInterface

copy()

Get a copy of the instance.

public copy() : static
Return values
static

create()

Create a new CarbonInterval instance from specific values.

public static create([int $years = null ][, int $months = null ][, int $weeks = null ][, int $days = null ][, int $hours = null ][, int $minutes = null ][, int $seconds = null ][, int $microseconds = null ]) : static

This is an alias for the constructor that allows better fluent syntax as it allows you to do CarbonInterval::create(1)->fn() rather than (new CarbonInterval(1))->fn().

Parameters
$years : int = null
$months : int = null
$weeks : int = null
$days : int = null
$hours : int = null
$minutes : int = null
$seconds : int = null
$microseconds : int = null
Tags
throws
Exception

when the interval_spec (passed as $years) cannot be parsed as an interval.

Return values
static

createFromFormat()

Parse a string into a new CarbonInterval object according to the specified format.

public static createFromFormat(string $format, string|null $interval) : static
Parameters
$format : string

Format of the $interval input string

$interval : string|null

Input string to convert into an interval

Tags
example 
echo Carboninterval::createFromFormat('H:i', '1:30');
throws
ParseErrorException

when the $interval cannot be parsed as an interval.

Return values
static

days()

public static days(mixed $days) : CarbonInterval

Create instance specifying a number of days or modify the number of days if called on an instance.

Parameters
$days : mixed
Return values
CarbonInterval

daysExcludeWeeks()

public static daysExcludeWeeks(mixed $days) : CarbonInterval

Create instance specifying a number of days or modify the number of days (keeping the current number of weeks) if called on an instance.

Parameters
$days : mixed
Return values
CarbonInterval

diff()

Create an interval from the difference between 2 dates.

public static diff(Carbon|DateTimeInterface|mixed $start[, Carbon|DateTimeInterface|mixed $end = null ][, bool $absolute = false ][, array<string|int, mixed> $skip = [] ]) : static
Parameters
$start : Carbon|DateTimeInterface|mixed
$end : Carbon|DateTimeInterface|mixed = null
$absolute : bool = false
$skip : array<string|int, mixed> = []
Return values
static

divide()

Divide and cascade current instance by a given divider.

public divide(float|int $divider) : $this
Parameters
$divider : float|int
Return values
$this

enableFloatSetters()

This option allow you to opt-in for the Carbon 3 behavior where float values will no longer be cast to integer (so truncated).

public static enableFloatSetters([bool $floatSettersEnabled = true ]) : void

⚠️ This settings will be applied globally, which mean your whole application code including the third-party dependencies that also may use Carbon will adopt the new behavior.

Parameters
$floatSettersEnabled : bool = true

eq()

Determines if the instance is equal to another

public eq(CarbonInterval|DateInterval|mixed $interval) : bool
Parameters
$interval : CarbonInterval|DateInterval|mixed
Tags
see
equalTo()
Return values
bool

floor()

Round the current instance second with given precision if specified.

public floor([DateInterval|string|float|int $precision = 1 ]) : $this
Parameters
$precision : DateInterval|string|float|int = 1
Tags
throws
Exception
Return values
$this

floorCenturies()

public floorCenturies(int|float $precision = 1) : $this

Truncate the current instance century with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorCentury()

public floorCentury(int|float $precision = 1) : $this

Truncate the current instance century with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorDay()

public floorDay(int|float $precision = 1) : $this

Truncate the current instance day with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorDays()

public floorDays(int|float $precision = 1) : $this

Truncate the current instance day with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorDecade()

public floorDecade(int|float $precision = 1) : $this

Truncate the current instance decade with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorDecades()

public floorDecades(int|float $precision = 1) : $this

Truncate the current instance decade with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorHour()

public floorHour(int|float $precision = 1) : $this

Truncate the current instance hour with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorHours()

public floorHours(int|float $precision = 1) : $this

Truncate the current instance hour with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorMicrosecond()

public floorMicrosecond(int|float $precision = 1) : $this

Truncate the current instance microsecond with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorMicroseconds()

public floorMicroseconds(int|float $precision = 1) : $this

Truncate the current instance microsecond with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorMillennia()

public floorMillennia(int|float $precision = 1) : $this

Truncate the current instance millennium with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorMillennium()

public floorMillennium(int|float $precision = 1) : $this

Truncate the current instance millennium with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorMillisecond()

public floorMillisecond(int|float $precision = 1) : $this

Truncate the current instance millisecond with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorMilliseconds()

public floorMilliseconds(int|float $precision = 1) : $this

Truncate the current instance millisecond with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorMinute()

public floorMinute(int|float $precision = 1) : $this

Truncate the current instance minute with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorMinutes()

public floorMinutes(int|float $precision = 1) : $this

Truncate the current instance minute with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorMonth()

public floorMonth(int|float $precision = 1) : $this

Truncate the current instance month with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorMonths()

public floorMonths(int|float $precision = 1) : $this

Truncate the current instance month with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorQuarter()

public floorQuarter(int|float $precision = 1) : $this

Truncate the current instance quarter with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorQuarters()

public floorQuarters(int|float $precision = 1) : $this

Truncate the current instance quarter with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorSecond()

public floorSecond(int|float $precision = 1) : $this

Truncate the current instance second with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorSeconds()

public floorSeconds(int|float $precision = 1) : $this

Truncate the current instance second with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorUnit()

Truncate the current instance at the given unit with given precision if specified.

public floorUnit(string $unit[, float|int|string|DateInterval|null $precision = 1 ]) : $this
Parameters
$unit : string
$precision : float|int|string|DateInterval|null = 1
Tags
throws
Exception
Return values
$this

floorWeek()

public floorWeek(int|float $precision = 1) : $this

Truncate the current instance day with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorWeeks()

public floorWeeks(int|float $precision = 1) : $this

Truncate the current instance day with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorYear()

public floorYear(int|float $precision = 1) : $this

Truncate the current instance year with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

floorYears()

public floorYears(int|float $precision = 1) : $this

Truncate the current instance year with given precision.

Parameters
$precision = 1 : int|float
Return values
$this

forHumans()

Get the current interval in a human readable format in the current locale.

public forHumans([int|array<string|int, mixed> $syntax = null ][, bool $short = false ][, int $parts = self::NO_LIMIT ][, int $options = null ]) : string
Parameters
$syntax : int|array<string|int, mixed> = null

if array passed, parameters will be extracted from it, the array may contain: ⦿ 'syntax' entry (see below) ⦿ 'short' entry (see below) ⦿ 'parts' entry (see below) ⦿ 'options' entry (see below) ⦿ 'skip' entry, list of units to skip (array of strings or a single string, it can be the unit name (singular or plural) or its shortcut (y, m, w, d, h, min, s, ms, µs). ⦿ 'aUnit' entry, prefer "an hour" over "1 hour" if true ⦿ 'altNumbers' entry, use alternative numbers if available (from the current language if true is passed, from the given language(s) if array or string is passed) ⦿ 'join' entry determines how to join multiple parts of the string - if $join is a string, it's used as a joiner glue - if $join is a callable/closure, it get the list of string and should return a string - if $join is an array, the first item will be the default glue, and the second item will be used instead of the glue for the last item - if $join is true, it will be guessed from the locale ('list' translation file entry) - if $join is missing, a space will be used as glue ⦿ 'minimumUnit' entry determines the smallest unit of time to display can be long or ` short form of the units, e.g. 'hour' or 'h' (default value: s) ⦿ 'locale' language in which the diff should be output (has no effect if 'translator' key is set) ⦿ 'translator' a custom translator to use to translator the output. if int passed, it adds modifiers: Possible values:

  • CarbonInterface::DIFF_ABSOLUTE no modifiers
  • CarbonInterface::DIFF_RELATIVE_TO_NOW add ago/from now modifier
  • CarbonInterface::DIFF_RELATIVE_TO_OTHER add before/after modifier Default value: CarbonInterface::DIFF_ABSOLUTE
$short : bool = false

displays short format of time units

$parts : int = self::NO_LIMIT

maximum number of parts to display (default value: -1: no limits)

$options : int = null

human diff options

Tags
example 
echo CarbonInterval::fromString('4d 3h 40m')->forHumans() . "\n";
echo CarbonInterval::fromString('4d 3h 40m')->forHumans(['parts' => 2]) . "\n";
echo CarbonInterval::fromString('4d 3h 40m')->forHumans(['parts' => 3, 'join' => true]) . "\n";
echo CarbonInterval::fromString('4d 3h 40m')->forHumans(['short' => true]) . "\n";
echo CarbonInterval::fromString('1d 24h')->forHumans(['join' => ' or ']) . "\n";
echo CarbonInterval::fromString('1d 24h')->forHumans(['minimumUnit' => 'hour']) . "\n";
throws
Exception
Return values
string

format()

public format(string $format) : string
Parameters
$format : string
Return values
string

fromString()

Creates a CarbonInterval from string.

public static fromString(string $intervalDefinition) : static

Format:

Suffix Unit Example DateInterval expression
y years 1y P1Y
mo months 3mo P3M
w weeks 2w P2W
d days 28d P28D
h hours 4h PT4H
m minutes 12m PT12M
s seconds 59s PT59S

e. g. 1w 3d 4h 32m 23s is converted to 10 days 4 hours 32 minutes and 23 seconds.

Special cases:

  • An empty string will return a zero interval
  • Fractions are allowed for weeks, days, hours and minutes and will be converted and rounded to the next smaller value (caution: 0.5w = 4d)
Parameters
$intervalDefinition : string
Tags
throws
InvalidIntervalException
Return values
static

get()

Get a part of the CarbonInterval object.

public get(Unit|string $name) : int|float|string|null
Parameters
$name : Unit|string
Return values
int|float|string|null

getCascadeFactors()

Mapping of units and factors for cascading.

public static getCascadeFactors() : array<string|int, mixed>

Should only be modified by changing the factors or referenced constants.

Return values
array<string|int, mixed>

getDateIntervalSpec()

Get the interval_spec string of a date interval.

public static getDateIntervalSpec(DateInterval $interval[, bool $microseconds = false ][, array<string|int, mixed> $skip = [] ]) : string
Parameters
$interval : DateInterval
$microseconds : bool = false
$skip : array<string|int, mixed> = []
Return values
string

getDaysPerWeek()

Returns current config for days per week.

public static getDaysPerWeek() : int|float
Return values
int|float

getFactor()

Returns the factor for a given source-to-target couple.

public static getFactor(string $source, string $target) : int|float|null
Parameters
$source : string
$target : string
Return values
int|float|null

getFactorWithDefault()

Returns the factor for a given source-to-target couple if set, else try to find the appropriate constant as the factor, such as Carbon::DAYS_PER_WEEK.

public static getFactorWithDefault(string $source, string $target) : int|float|null
Parameters
$source : string
$target : string
Return values
int|float|null

getHoursPerDay()

Returns current config for hours per day.

public static getHoursPerDay() : int|float
Return values
int|float

getMicrosecondsPerMillisecond()

Returns current config for microseconds per second.

public static getMicrosecondsPerMillisecond() : int|float
Return values
int|float

getMillisecondsPerSecond()

Returns current config for microseconds per second.

public static getMillisecondsPerSecond() : int|float
Return values
int|float

getMinutesPerHour()

Returns current config for minutes per hour.

public static getMinutesPerHour() : int|float
Return values
int|float

getNonZeroValues()

Returns interval non-zero values as an array where key are the unit names and values the counts.

public getNonZeroValues() : array<string|int, int>
Return values
array<string|int, int>

getSecondsPerMinute()

Returns current config for seconds per minute.

public static getSecondsPerMinute() : int|float
Return values
int|float

getSettings()

Returns current local settings.

public getSettings() : array<string|int, mixed>
Return values
array<string|int, mixed>

getStep()

Get the dynamic step in use.

public getStep() : Closure
Return values
Closure

getValuesSequence()

Returns interval values as an array where key are the unit names and values the counts from the biggest non-zero one the the smallest non-zero one.

public getValuesSequence() : array<string|int, int>
Return values
array<string|int, int>

greaterThan()

Determines if the instance is greater (longer) than another

public greaterThan(CarbonInterval|DateInterval|mixed $interval) : bool
Parameters
$interval : CarbonInterval|DateInterval|mixed
Return values
bool

greaterThanOrEqualTo()

Determines if the instance is greater (longer) than or equal to another

public greaterThanOrEqualTo(CarbonInterval|DateInterval|mixed $interval) : bool
Parameters
$interval : CarbonInterval|DateInterval|mixed
Return values
bool

gt()

Determines if the instance is greater (longer) than another

public gt(CarbonInterval|DateInterval|mixed $interval) : bool
Parameters
$interval : CarbonInterval|DateInterval|mixed
Tags
see
greaterThan()
Return values
bool

gte()

Determines if the instance is greater (longer) than or equal to another

public gte(CarbonInterval|DateInterval|mixed $interval) : bool
Parameters
$interval : CarbonInterval|DateInterval|mixed
Tags
see
greaterThanOrEqualTo()
Return values
bool

hasMacro()

Check if macro is registered.

public static hasMacro(string $name) : bool
Parameters
$name : string
Return values
bool

hasNegativeValues()

public hasNegativeValues() : bool
Return values
bool

hasPositiveValues()

public hasPositiveValues() : bool
Return values
bool

hours()

public static hours(mixed $hours) : CarbonInterval

Create instance specifying a number of hours or modify the number of hours if called on an instance.

Parameters
$hours : mixed
Return values
CarbonInterval

instance()

Create a CarbonInterval instance from a DateInterval one. Can not instance DateInterval objects created from DateTime::diff() as you can't externally set the $days field.

public static instance(DateInterval $interval[, array<string|int, mixed> $skip = [] ][, bool $skipCopy = false ]) : static
Parameters
$interval : DateInterval
$skip : array<string|int, mixed> = []
$skipCopy : bool = false

set to true to return the passed object (without copying it) if it's already of the current class

Return values
static

invert()

Invert the interval.

public invert([bool|int $inverted = null ]) : $this
Parameters
$inverted : bool|int = null

if a parameter is passed, the passed value cast as 1 or 0 is used as the new value of the ->invert property.

Return values
$this

isBetween()

Determines if the instance is between two others

public isBetween(CarbonInterval|DateInterval|mixed $interval1, CarbonInterval|DateInterval|mixed $interval2[, bool $equal = true ]) : bool
Parameters
$interval1 : CarbonInterval|DateInterval|mixed
$interval2 : CarbonInterval|DateInterval|mixed
$equal : bool = true

Indicates if an equal to comparison should be done

Tags
example 
CarbonInterval::hours(48)->isBetween(CarbonInterval::day(), CarbonInterval::days(3)); // true
CarbonInterval::hours(48)->isBetween(CarbonInterval::day(), CarbonInterval::hours(36)); // false
CarbonInterval::hours(48)->isBetween(CarbonInterval::day(), CarbonInterval::days(2)); // true
CarbonInterval::hours(48)->isBetween(CarbonInterval::day(), CarbonInterval::days(2), false); // false
Return values
bool

isEmpty()

Returns true if the interval is empty for each unit.

public isEmpty() : bool
Return values
bool

lessThan()

Determines if the instance is less (shorter) than another

public lessThan(CarbonInterval|DateInterval|mixed $interval) : bool
Parameters
$interval : CarbonInterval|DateInterval|mixed
Return values
bool

lessThanOrEqualTo()

Determines if the instance is less (shorter) than or equal to another

public lessThanOrEqualTo(CarbonInterval|DateInterval|mixed $interval) : bool
Parameters
$interval : CarbonInterval|DateInterval|mixed
Return values
bool

lt()

Determines if the instance is less (shorter) than another

public lt(CarbonInterval|DateInterval|mixed $interval) : bool
Parameters
$interval : CarbonInterval|DateInterval|mixed
Tags
see
lessThan()
Return values
bool

lte()

Determines if the instance is less (shorter) than or equal to another

public lte(CarbonInterval|DateInterval|mixed $interval) : bool
Parameters
$interval : CarbonInterval|DateInterval|mixed
Tags
see
lessThanOrEqualTo()
Return values
bool

macro()

Register a custom macro.

public static macro(string $name, callable|null $macro) : void

Pass null macro to remove it.

Parameters
$name : string
$macro : callable|null
Tags
example 
CarbonInterval::macro('twice', function () {
  return $this->times(2);
});
echo CarbonInterval::hours(2)->twice();

make()

Make a CarbonInterval instance from given variable if possible.

public static make(mixed|int|DateInterval|string|Closure|Unit|null $interval[, Unit|string|null $unit = null ][, bool $skipCopy = false ]) : static|null

Always return a new instance. Parse only strings and only these likely to be intervals (skip dates and recurrences). Throw an exception for invalid format, but otherwise return null.

Parameters
$interval : mixed|int|DateInterval|string|Closure|Unit|null

interval or number of the given $unit

$unit : Unit|string|null = null

if specified, $interval must be an integer

$skipCopy : bool = false

set to true to return the passed object (without copying it) if it's already of the current class

Return values
static|null

microseconds()

public static microseconds(mixed $microseconds) : CarbonInterval

Create instance specifying a number of microseconds or modify the number of microseconds if called on an instance.

Parameters
$microseconds : mixed
Return values
CarbonInterval

milliseconds()

public static milliseconds(mixed $milliseconds) : CarbonInterval

Create instance specifying a number of milliseconds or modify the number of milliseconds if called on an instance.

Parameters
$milliseconds : mixed
Return values
CarbonInterval

minus()

Add given parameters to the current interval.

public minus([int $years = 0 ][, int $months = 0 ][, int|float $weeks = 0 ][, int|float $days = 0 ][, int|float $hours = 0 ][, int|float $minutes = 0 ][, int|float $seconds = 0 ][, int|float $microseconds = 0 ]) : $this
Parameters
$years : int = 0
$months : int = 0
$weeks : int|float = 0
$days : int|float = 0
$hours : int|float = 0
$minutes : int|float = 0
$seconds : int|float = 0
$microseconds : int|float = 0
Return values
$this

minutes()

public static minutes(mixed $minutes) : CarbonInterval

Create instance specifying a number of minutes or modify the number of minutes if called on an instance.

Parameters
$minutes : mixed
Return values
CarbonInterval

mixin()

Register macros from a mixin object.

public static mixin(object|string $mixin) : void
Parameters
$mixin : object|string
Tags
example 
CarbonInterval::mixin(new class {
  public function daysToHours() {
    return function () {
      $this->hours += $this->days;
      $this->days = 0;

      return $this;
    };
  }
  public function hoursToDays() {
    return function () {
      $this->days += $this->hours;
      $this->hours = 0;

      return $this;
    };
  }
});
echo CarbonInterval::hours(5)->hoursToDays() . "\n";
echo CarbonInterval::days(5)->daysToHours() . "\n";
throws
ReflectionException

months()

public static months(mixed $months) : CarbonInterval

Create instance specifying a number of months or modify the number of months if called on an instance.

Parameters
$months : mixed
Return values
CarbonInterval

multiply()

Multiply and cascade current instance by a given factor.

public multiply(float|int $factor) : $this
Parameters
$factor : float|int
Return values
$this

ne()

Determines if the instance is not equal to another

public ne(CarbonInterval|DateInterval|mixed $interval) : bool
Parameters
$interval : CarbonInterval|DateInterval|mixed
Tags
see
notEqualTo()
Return values
bool

notEqualTo()

Determines if the instance is not equal to another

public notEqualTo(CarbonInterval|DateInterval|mixed $interval) : bool
Parameters
$interval : CarbonInterval|DateInterval|mixed
Return values
bool

optimize()

Get rid of the original input, start date and end date that may be kept in memory.

public optimize() : $this
Return values
$this

original()

Return the original source used to create the current interval.

public original() : array<string|int, mixed>|int|string|DateInterval|mixed|null
Return values
array<string|int, mixed>|int|string|DateInterval|mixed|null

parseFromLocale()

Creates a CarbonInterval from string using a different locale.

public static parseFromLocale(string $interval[, string|null $locale = null ]) : static
Parameters
$interval : string

interval string in the given language (may also contain English).

$locale : string|null = null

if locale is null or not specified, current global locale will be used instead.

Return values
static

plus()

Add given parameters to the current interval.

public plus([int $years = 0 ][, int $months = 0 ][, int|float $weeks = 0 ][, int|float $days = 0 ][, int|float $hours = 0 ][, int|float $minutes = 0 ][, int|float $seconds = 0 ][, int|float $microseconds = 0 ]) : $this
Parameters
$years : int = 0
$months : int = 0
$weeks : int|float = 0
$days : int|float = 0
$hours : int|float = 0
$minutes : int|float = 0
$seconds : int|float = 0
$microseconds : int|float = 0
Return values
$this

resetToStringFormat()

Reset the format used to the default when type juggling a Carbon instance to a string

public static resetToStringFormat() : void

round()

Round the current instance second with given precision if specified.

public round([float|int|string|DateInterval|null $precision = 1 ][, string $function = 'round' ]) : $this
Parameters
$precision : float|int|string|DateInterval|null = 1
$function : string = 'round'
Tags
throws
Exception
Return values
$this

roundCenturies()

public roundCenturies(int|float $precision = 1, string $function = "round") : $this

Round the current instance century with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundCentury()

public roundCentury(int|float $precision = 1, string $function = "round") : $this

Round the current instance century with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundDay()

public roundDay(int|float $precision = 1, string $function = "round") : $this

Round the current instance day with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundDays()

public roundDays(int|float $precision = 1, string $function = "round") : $this

Round the current instance day with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundDecade()

public roundDecade(int|float $precision = 1, string $function = "round") : $this

Round the current instance decade with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundDecades()

public roundDecades(int|float $precision = 1, string $function = "round") : $this

Round the current instance decade with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundHour()

public roundHour(int|float $precision = 1, string $function = "round") : $this

Round the current instance hour with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundHours()

public roundHours(int|float $precision = 1, string $function = "round") : $this

Round the current instance hour with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundMicrosecond()

public roundMicrosecond(int|float $precision = 1, string $function = "round") : $this

Round the current instance microsecond with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundMicroseconds()

public roundMicroseconds(int|float $precision = 1, string $function = "round") : $this

Round the current instance microsecond with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundMillennia()

public roundMillennia(int|float $precision = 1, string $function = "round") : $this

Round the current instance millennium with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundMillennium()

public roundMillennium(int|float $precision = 1, string $function = "round") : $this

Round the current instance millennium with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundMillisecond()

public roundMillisecond(int|float $precision = 1, string $function = "round") : $this

Round the current instance millisecond with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundMilliseconds()

public roundMilliseconds(int|float $precision = 1, string $function = "round") : $this

Round the current instance millisecond with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundMinute()

public roundMinute(int|float $precision = 1, string $function = "round") : $this

Round the current instance minute with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundMinutes()

public roundMinutes(int|float $precision = 1, string $function = "round") : $this

Round the current instance minute with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundMonth()

public roundMonth(int|float $precision = 1, string $function = "round") : $this

Round the current instance month with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundMonths()

public roundMonths(int|float $precision = 1, string $function = "round") : $this

Round the current instance month with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundQuarter()

public roundQuarter(int|float $precision = 1, string $function = "round") : $this

Round the current instance quarter with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundQuarters()

public roundQuarters(int|float $precision = 1, string $function = "round") : $this

Round the current instance quarter with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundSecond()

public roundSecond(int|float $precision = 1, string $function = "round") : $this

Round the current instance second with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundSeconds()

public roundSeconds(int|float $precision = 1, string $function = "round") : $this

Round the current instance second with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundUnit()

Round the current instance at the given unit with given precision if specified and the given function.

public roundUnit(string $unit[, DateInterval|string|int|float $precision = 1 ][, string $function = 'round' ]) : static
Parameters
$unit : string
$precision : DateInterval|string|int|float = 1
$function : string = 'round'
Tags
throws
Exception
Return values
static

roundWeek()

public roundWeek(int|float $precision = 1, string $function = "round") : $this

Round the current instance day with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundWeeks()

public roundWeeks(int|float $precision = 1, string $function = "round") : $this

Round the current instance day with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundYear()

public roundYear(int|float $precision = 1, string $function = "round") : $this

Round the current instance year with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

roundYears()

public roundYears(int|float $precision = 1, string $function = "round") : $this

Round the current instance year with given precision using the given function.

Parameters
$precision = 1 : int|float
$function = "round" : string
Return values
$this

seconds()

public static seconds(mixed $seconds) : CarbonInterval

Create instance specifying a number of seconds or modify the number of seconds if called on an instance.

Parameters
$seconds : mixed
Return values
CarbonInterval

set()

Set a part of the CarbonInterval object.

public set(Unit|string|array<string|int, mixed> $name[, int $value = null ]) : $this
Parameters
$name : Unit|string|array<string|int, mixed>
$value : int = null
Tags
throws
UnknownSetterException
Return values
$this

setCascadeFactors()

Set default cascading factors for ->cascade() method.

public static setCascadeFactors(array<string|int, mixed> $cascadeFactors) : mixed
Parameters
$cascadeFactors : array<string|int, mixed>

setStep()

Set a step to apply instead of a fixed interval to get the new date.

public setStep(Closure|null $step) : void

Or pass null to switch to fixed interval.

Parameters
$step : Closure|null

setTimezone()

Set the instance's timezone from a string or object.

public setTimezone(DateTimeZone|string|int $timezone) : static
Parameters
$timezone : DateTimeZone|string|int
Return values
static

settings()

Set specific options.

public settings(array<string|int, mixed> $settings) : $this|static
  • strictMode: true|false|null
  • monthOverflow: true|false|null
  • yearOverflow: true|false|null
  • humanDiffOptions: int|null
  • toStringFormat: string|Closure|null
  • toJsonFormat: string|Closure|null
  • locale: string|null
  • timezone: \DateTimeZone|string|int|null
  • macros: array|null
  • genericMacros: array|null
Parameters
$settings : array<string|int, mixed>
Return values
$this|static

setToStringFormat()

public static setToStringFormat(string|Closure|null $format) : void
Parameters
$format : string|Closure|null
Tags
deprecated

To avoid conflict between different third-party libraries, static setters should not be used. You should rather let Carbon object being cast to string with DEFAULT_TO_STRING_FORMAT, and use other method or custom format passed to format() method if you need to dump another string format.

Set the default format used when type juggling a Carbon instance to a string.

shares()

Divide current instance by a given divider. shares() is naive, it divides each unit separately and the result is rounded for each unit. So 5 hours and 20 minutes shared by 3 becomes 2 hours and 7 minutes.

public shares(float|int $divider) : $this

Use shares() when you want a fast and approximated calculation that does not cascade units.

For a precise and cascaded calculation,

Parameters
$divider : float|int
Tags
see
divide()
Return values
$this

shiftTimezone()

Set the instance's timezone from a string or object and add/subtract the offset difference.

public shiftTimezone(DateTimeZone|string|int $timezone) : static
Parameters
$timezone : DateTimeZone|string|int
Return values
static

spec()

Get the interval_spec string.

public spec([bool $microseconds = false ]) : string
Parameters
$microseconds : bool = false
Return values
string

stepBy()

Decompose the current interval into

public stepBy(mixed|int|DateInterval|string|Closure|Unit|null $interval[, Unit|string|null $unit = null ]) : CarbonPeriod
Parameters
$interval : mixed|int|DateInterval|string|Closure|Unit|null

interval or number of the given $unit

$unit : Unit|string|null = null

if specified, $interval must be an integer

Return values
CarbonPeriod

sub()

Subtract the passed interval to the current instance.

public sub(string|DateInterval $unit[, int|float $value = 1 ]) : $this
Parameters
$unit : string|DateInterval
$value : int|float = 1
Return values
$this

subDays()

public subDays(int|float $days) : $this

Subtract given number of days to the current interval

Parameters
$days : int|float
Return values
$this

subHours()

public subHours(int|float $hours) : $this

Subtract given number of hours to the current interval

Parameters
$hours : int|float
Return values
$this

subMicroseconds()

public subMicroseconds(int|float $microseconds) : $this

Subtract given number of microseconds to the current interval

Parameters
$microseconds : int|float
Return values
$this

subMilliseconds()

public subMilliseconds(int|float $milliseconds) : $this

Subtract given number of milliseconds to the current interval

Parameters
$milliseconds : int|float
Return values
$this

subMinutes()

public subMinutes(int|float $minutes) : $this

Subtract given number of minutes to the current interval

Parameters
$minutes : int|float
Return values
$this

subMonths()

public subMonths(int $months) : $this

Subtract given number of months to the current interval

Parameters
$months : int
Return values
$this

subSeconds()

public subSeconds(int|float $seconds) : $this

Subtract given number of seconds to the current interval

Parameters
$seconds : int|float
Return values
$this

subtract()

Subtract the passed interval to the current instance.

public subtract(string|DateInterval $unit[, int|float $value = 1 ]) : $this
Parameters
$unit : string|DateInterval
$value : int|float = 1
Return values
$this

subWeeks()

public subWeeks(int|float $weeks) : $this

Subtract given number of weeks to the current interval

Parameters
$weeks : int|float
Return values
$this

subYears()

public subYears(int $years) : $this

Subtract given number of years to the current interval

Parameters
$years : int
Return values
$this

times()

Multiply current instance given number of times. times() is naive, it multiplies each unit (so day can be greater than 31, hour can be greater than 23, etc.) and the result is rounded separately for each unit.

public times(float|int $factor) : $this

Use times() when you want a fast and approximated calculation that does not cascade units.

For a precise and cascaded calculation,

Parameters
$factor : float|int
Tags
see
multiply()
Return values
$this

toArray()

Returns interval values as an array where key are the unit names and values the counts.

public toArray() : array<string|int, int>
Return values
array<string|int, int>

toDateInterval()

Return native DateInterval PHP object matching the current instance.

public toDateInterval() : DateInterval
Tags
example 
var_dump(CarbonInterval::hours(2)->toDateInterval());
Return values
DateInterval

toPeriod()

Convert the interval to a CarbonPeriod.

public toPeriod(DateTimeInterface|string|int ...$params) : CarbonPeriod
Parameters
$params : DateTimeInterface|string|int

Start date, [end date or recurrences] and optional settings.

Return values
CarbonPeriod

weeks()

public static weeks(mixed $weeks) : CarbonInterval

Create instance specifying a number of weeks or modify the number of weeks if called on an instance.

Parameters
$weeks : mixed
Return values
CarbonInterval

weeksAndDays()

Allow setting of weeks and days to be cumulative.

public weeksAndDays(int $weeks, int $days) : static
Parameters
$weeks : int

Number of weeks to set

$days : int

Number of days to set

Return values
static

years()

public static years(mixed $years) : CarbonInterval

Create instance specifying a number of years or modify the number of years if called on an instance.

Parameters
$years : mixed
Return values
CarbonInterval

addExtraDebugInfos()

protected addExtraDebugInfos(array<string|int, mixed> &$infos) : void
Parameters
$infos : array<string|int, mixed>

bindMacroContext()

Stack a Carbon context from inside calls of self::this() and execute a given action.

protected static bindMacroContext(self|null $context, callable $callable) : mixed
Parameters
$context : self|null
$callable : callable

callMacro()

Call given macro.

protected callMacro(string $name, array<string|int, mixed> $parameters) : mixed
Parameters
$name : string
$parameters : array<string|int, mixed>

callRoundMethod()

protected callRoundMethod(string $method, array<string|int, mixed> $parameters) : static|null
Parameters
$method : string
$parameters : array<string|int, mixed>
Return values
static|null

context()

Return the current context from inside a macro callee or a null if static.

protected static context() : static|null
Return values
static|null

copyProperties()

protected copyProperties(self $interval[, mixed $ignoreSign = false ]) : static
Parameters
$interval : self
$ignoreSign : mixed = false
Return values
static

getDefaultCascadeFactors()

protected static getDefaultCascadeFactors() : array<string|int, mixed>
Return values
array<string|int, mixed>

getForHumansInitialVariables()

protected getForHumansInitialVariables(mixed $syntax, mixed $short) : array<string|int, mixed>
Parameters
$syntax : mixed
$short : mixed
Return values
array<string|int, mixed>

getForHumansParameters()

protected getForHumansParameters([mixed $syntax = null ][, mixed $short = false ][, mixed $parts = self::NO_LIMIT ][, mixed $options = null ]) : array<string|int, mixed>
Parameters
$syntax : mixed = null
$short : mixed = false
$parts : mixed = self::NO_LIMIT
$options : mixed = null
Return values
array<string|int, mixed>

getRoundingMethodFromOptions()

protected static getRoundingMethodFromOptions(int $options) : string|null
Parameters
$options : int
Return values
string|null

isLocalStrictModeEnabled()

protected isLocalStrictModeEnabled() : bool
Return values
bool

makeFromString()

protected static makeFromString(string $interval) : self|null
Parameters
$interval : string
Return values
self|null

resolveInterval()

protected resolveInterval(mixed $interval) : self|null
Parameters
$interval : mixed
Return values
self|null

roundWith()

protected roundWith(DateInterval|string|float|int $precision, callable|string $function) : static|null
Parameters
$precision : DateInterval|string|float|int
$function : callable|string
Return values
static|null

solveNegativeInterval()

protected solveNegativeInterval() : static
Return values
static

this()

Return the current context from inside a macro callee or a new one if static.

protected static this() : static
Return values
static

assertSafeForInteger()

Throw an exception if precision loss when storing the given value as an integer would be >= 1.0.

private assertSafeForInteger(string $name, mixed $value) : void
Parameters
$name : string
$value : mixed

castIntervalToClass()

private static castIntervalToClass(DateInterval $interval, string $className[, array<string|int, mixed> $skip = [] ]) : T
Parameters
$interval : DateInterval
$className : string
$skip : array<string|int, mixed> = []
Tags
template

T of DateInterval

psalm-param

class-string<T> $className

Return values
T

checkIntegerValue()

private checkIntegerValue(string $name, mixed $value) : void
Parameters
$name : string
$value : mixed

copyNegativeUnits()

private static copyNegativeUnits(DateInterval $from, DateInterval $to) : void
Parameters
$from : DateInterval
$to : DateInterval

copyStep()

private static copyStep(self $from, self $to) : void
Parameters
$from : self
$to : self

doCascade()

private doCascade(bool $deep) : static
Parameters
$deep : bool
Return values
static

getAnonymousClassCodeForTrait()

private static getAnonymousClassCodeForTrait(string $trait) : string
Parameters
$trait : string
Return values
string

getFlipCascadeFactors()

private static getFlipCascadeFactors() : array<string|int, mixed>
Return values
array<string|int, mixed>

getInnerValues()

private getInnerValues() : array<string|int, mixed>
Return values
array<string|int, mixed>

getMagicParameter()

private getMagicParameter(array<string|int, mixed> $parameters, int $index, string $key, mixed $default) : mixed
Parameters
$parameters : array<string|int, mixed>
$index : int
$key : string
$default : mixed

getMixableMethods()

private static getMixableMethods(self $context) : Generator
Parameters
$context : self
Return values
Generator

handleDecimalPart()

private handleDecimalPart(string $unit, mixed $value, mixed $integerValue) : void
Parameters
$unit : string
$value : mixed
$integerValue : mixed

invertCascade()

private invertCascade(array<string|int, mixed> $values) : static
Parameters
$values : array<string|int, mixed>
Return values
static

loadMixinClass()

private static loadMixinClass(object|string $mixin) : void
Parameters
$mixin : object|string
Tags
throws
ReflectionException

loadMixinTrait()

private static loadMixinTrait(string $trait) : void
Parameters
$trait : string

needsDeclension()

private needsDeclension(string $mode, int $index, int $parts) : bool
Parameters
$mode : string
$index : int
$parts : int
Return values
bool

resolveCarbon()

Convert DateTimeImmutable instance to CarbonImmutable instance and DateTime instance to Carbon instance.

private resolveCarbon(DateTimeInterface $dateTime) : Carbon|CarbonImmutable
Parameters
$dateTime : DateTimeInterface
Return values
Carbon|CarbonImmutable

setSetting()

private setSetting(string $setting, mixed $value) : $this
Parameters
$setting : string
$value : mixed
Return values
$this

standardizeUnit()

private static standardizeUnit(string $unit) : string
Parameters
$unit : string
Return values
string

transmitFactory()

Trigger the given action using the local factory of the object, so it will be transmitted to any object also using this trait and calling initLocalFactory() in its constructor.

private transmitFactory(Closure $action) : T
Parameters
$action : Closure
Tags
template

T

Return values
T

withOriginal()

private static withOriginal(T $interval, mixed $original) : T
Parameters
$interval : T
$original : mixed
Tags
template

T

Return values
T 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results