class CarbonInterval extendsDateInterval implementsCarbonConverterInterface

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.

Traits

Trait to call rounding methods to interval or the interval of a period.
Trait Mixin.
Trait Options.
Trait Localization.

Constants

PERIOD_PREFIX

Interval spec period designators

PERIOD_YEARS

PERIOD_MONTHS

PERIOD_DAYS

PERIOD_TIME_PREFIX

PERIOD_HOURS

PERIOD_MINUTES

PERIOD_SECONDS

Properties

protectedClosure|null $step Step to apply instead of a fixed interval to get the new date. from IntervalStep
staticprotectedarray $macroContextStack Stack of macro instance contexts. from Mixin
staticprotectedTranslatorInterface $translator A translator to .
protectedTranslatorInterface $localTranslator Specific translator of the current instance. from Localization
staticprotectedint $humanDiffOptions Options for diffForHumans(). from Localization
staticint $PHPIntSize Customizable PHP_INT_SIZE override. from Options
staticprotectedint|string $weekStartsAt First day of week. from Options
staticprotectedint|string $weekEndsAt Last day of week. from Options
staticprotectedarray $weekendDays Days of weekend. from Options
staticprotectedarray $regexFormats Format regex patterns. from Options
staticprotectedarray $regexFormatModifiers Format modifiers (such as available in createFromFormat) regex patterns. from Options
staticprotectedbool $monthsOverflow Indicates if months should be calculated with overflow. from Options
staticprotectedbool $yearsOverflow Indicates if years should be calculated with overflow. from Options
staticprotectedbool $strictModeEnabled Indicates if the strict mode is in use. from Options
staticprotectedstring|callable|null $formatFunction Function to call instead of format. from Options
staticprotectedstring|callable|null $createFromFormatFunction Function to call instead of createFromFormat. from Options
staticprotectedstring|callable|null $parseFunction Function to call instead of parse. from Options
protectedbool|null $localMonthsOverflow Indicates if months should be calculated with overflow. from Options
protectedbool|null $localYearsOverflow Indicates if years should be calculated with overflow. from Options
protectedbool|null $localStrictModeEnabled Indicates if the strict mode is in use. from Options
protectedbool|null $localHumanDiffOptions Options for diffForHumans and forHumans methods. from Options
protectedstring|null $localToStringFormat Format to use on string cast. from Options
protectedstring|null $localSerializer Format to use on JSON serialization. from Options
protectedarray|null $localMacros Instance-specific macros. from Options
protectedarray|null $localGenericMacros Instance-specific generic macros. from Options
protectedstring|callable|null $localFormatFunction Function to call instead of format. from Options
staticprotectedarray|null $cascadeFactors
staticprotectedarray $formats
staticprotectedarray $macros The registered macros.
protectedmixed $tzName Timezone handler for settings() method.
int $years Total years of the current interval.
int $months Total months of the current interval.
int $weeks Total weeks of the current interval calculated from the days.
int $dayz Total days of the current interval (weeks * 7 + days).
int $hours Total hours of the current interval.
int $minutes Total minutes of the current interval.
int $seconds Total seconds of the current interval.
int $microseconds Total microseconds of the current interval.
int $milliseconds Total microseconds of the current interval.
int $microExcludeMilli Remaining microseconds without the milliseconds.
int $dayzExcludeWeeks Total days remaining in the final week of the current instance (days % 7).
int $daysExcludeWeeks alias of dayzExcludeWeeks

Methods

callRoundMethod(string$method,array$parameters)

No description

roundWith($precision,$function)

No description

getStep()

Get the dynamic step in use.

setStep(Closure|null$step)

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

convertDate(DateTimeInterface$dateTime,bool$negated =false)

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

static void
mixin(object|string$mixin)

Register macros from a mixin object.

static mixed
bindMacroContext(Mixin|null$context,callable$callable)

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

from Mixin
static Mixin|null
context()

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

from Mixin
this()

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

static 
setHumanDiffOptions(int$humanDiffOptions)deprecated

No description

static 
enableHumanDiffOption(int$humanDiffOption)deprecated

No description

static 
disableHumanDiffOption(int$humanDiffOption)deprecated

No description

static int
getHumanDiffOptions()

Return default humanDiff() options (merged flags as integer).

static TranslatorInterface
getTranslator()

Get the default translator instance in use.

static void
setTranslator(TranslatorInterface$translator)

Set the default translator instance to use.

bool
hasLocalTranslator()

Return true if the current instance has its own translator.

TranslatorInterface
getLocalTranslator()

Get the translator of the current instance or the default if none set.

$this
setLocalTranslator(TranslatorInterface$translator)

Set the translator for the current instance.

static string
getTranslationMessageWith(TranslatorInterface$translator,string$key,string|null$locale =null,string|null$default =null)

Returns raw translation message for a given key.

string
getTranslationMessage(string$key,string|null$locale =null,string|null$default =null,TranslatorInterface$translator =null)

Returns raw translation message for a given key.

static string
translateWith(TranslatorInterface$translator,string$key,array$parameters =[],null$number =null)

Translate using translation string or callback available.

string
translate(string$key,array$parameters =[],string|int|float|null$number =null,TranslatorInterface|null$translator =null,bool$altNumbers =false)

Translate using translation string or callback available.

string
translateNumber(int$number)

Returns the alternative number for a given integer if available in the current locale.

static string
translateTimeString(string$timeString,string|null$from =null,string|null$to =null,int$mode =CarbonInterface::TRANSLATE_ALL)

Translate a time string from a locale to an other.

string
translateTimeStringTo(string$timeString,string|null$to =null)

Translate a time string from the current locale ($date->locale()) to an other.

$this|string
locale(string$locale =null,string...$fallbackLocales)

Get/set the locale for the current instance.

static string
getLocale()

Get the current translator locale.

static bool
setLocale(string$locale)

Set the current translator locale and indicate if the source locale file exists.

static 
setFallbackLocale(string$locale)

Set the fallback locale.

static string|null
getFallbackLocale()

Get the fallback locale.

static mixed
executeWithLocale(string$locale,callable$func)

Set the current locale to the given, execute the passed function, reset the locale to previous one, then return the result of the closure (or null if the closure was void).

static bool
localeHasShortUnits(string$locale)

Returns true if the given locale is internally supported and has short-units support.

static bool
localeHasDiffSyntax(string$locale)

Returns true if the given locale is internally supported and has diff syntax support (ago, from now, before, after).

static bool
localeHasDiffOneDayWords(string$locale)

Returns true if the given locale is internally supported and has words for 1-day diff (just now, yesterday, tomorrow).

static bool
localeHasDiffTwoDayWords(string$locale)

Returns true if the given locale is internally supported and has words for 2-days diff (before yesterday, after tomorrow).

static bool
localeHasPeriodSyntax(string$locale)

Returns true if the given locale is internally supported and has period syntax support (X times, every X, from X, to X).

static array
getAvailableLocales()

Returns the list of internally available locales and already loaded custom locales.

static Language[]
getAvailableLocalesInfo()

Returns list of Language object for each available locale. This object allow you to get the ISO name, native name, region and variant of the locale.

static TranslatorInterface
translator()

Initialize the default translator instance if necessary.

string|null
getTranslatorLocale(null$translator =null)

Get the locale of a given translator.

static LocaleAwareInterface|null
getLocaleAwareTranslator(LocaleAwareInterface|null$translator =null)

Throw an error if passed object is not LocaleAwareInterface.

static 
useStrictMode(bool$strictModeEnabled =true)deprecated

No description

from Options
static bool
isStrictModeEnabled()

Returns true if the strict mode is globally in use, false else.

from Options
static void
useMonthsOverflow(bool$monthsOverflow =true)deprecated

No description

from Options
static void
resetMonthsOverflow()deprecated

No description

from Options
static bool
shouldOverflowMonths()

Get the month overflow global behavior (can be overridden in specific instances).

from Options
static void
useYearsOverflow(bool$yearsOverflow =true)deprecated

No description

from Options
static void
resetYearsOverflow()deprecated

No description

from Options
static bool
shouldOverflowYears()

Get the month overflow global behavior (can be overridden in specific instances).

from Options
$this|Options
settings(array$settings)

Set specific options.

from Options
array
getSettings()

Returns current local settings.

from Options
array
__debugInfo()

Show truthy properties on var_dump().

from Options
addExtraDebugInfos($infos)

No description

from Options
shiftTimezone(DateTimeZone|string$tzName)

No description

setTimezone(DateTimeZone|string$tzName)

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

static array
getCascadeFactors()

Mapping of units and factors for cascading.

static 
setCascadeFactors(array$cascadeFactors)

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

__construct(Closure|DateInterval|string|int|null$years =1,int|null$months =null,int|null$weeks =null,int|null$days =null,int|null$hours =null,int|null$minutes =null,int|null$seconds =null,int|null$microseconds =null)

Create a new CarbonInterval instance.

static int|float|null
getFactor(string$source,string$target)

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

static int|float|null
getFactorWithDefault(string$source,string$target)

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.

static int|float
getDaysPerWeek()

Returns current config for days per week.

static int|float
getHoursPerDay()

Returns current config for hours per day.

static int|float
getMinutesPerHour()

Returns current config for minutes per hour.

static int|float
getSecondsPerMinute()

Returns current config for seconds per minute.

static int|float
getMillisecondsPerSecond()

Returns current config for microseconds per second.

static int|float
getMicrosecondsPerMillisecond()

Returns current config for microseconds per second.

create(int$years =1,int$months =null,int$weeks =null,int$days =null,int$hours =null,int$minutes =null,int$seconds =null,int$microseconds =null)

Create a new CarbonInterval instance from specific values.

createFromFormat(string$format,string|null$interval)

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

copy()

Get a copy of the instance.

clone()

Get a copy of the instance.

static CarbonInterval|null
__callStatic(string$method,array$parameters)

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

fromString(string$intervalDefinition)

Creates a CarbonInterval from string.

parseFromLocale(string$interval,string|null$locale =null)

Creates a CarbonInterval from string using a different locale.

cast(string$className)

Cast the current instance into the given class.

instance(DateInterval$interval)

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.

static CarbonInterval|null
make(mixed|int|DateInterval|string|Closure|null$interval,string|null$unit =null)

Make a CarbonInterval instance from given variable if possible.

static 
makeFromString(string$interval)

No description

resolveInterval($interval)

No description

static 
createFromDateString($time)

No description

int|float|string
get(string$name)

Get a part of the CarbonInterval object.

int|float|string
__get(string$name)

Get a part of the CarbonInterval object.

$this
set(string|array$name,int$value =null)

Set a part of the CarbonInterval object.

__set(string$name,int$value)

Set a part of the CarbonInterval object.

weeksAndDays(int$weeks,int$days)

Allow setting of weeks and days to be cumulative.

bool
isEmpty()

Returns true if the interval is empty for each unit.

static void
macro(string$name,object|callable$macro)

Register a custom macro.

static bool
hasMacro(string$name)

Check if macro is registered.

mixed
callMacro(string$name,array$parameters)

Call given macro.

__call(string$method,array$parameters)

Allow fluent calls on the setters.

getForHumansInitialVariables($syntax,$short)

No description

array
getForHumansParameters(mixed$syntax =null,mixed$short =false,mixed$parts =-1,mixed$options =null)

No description

static 
getRoundingMethodFromOptions(int$options)

No description

int[]
toArray()

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

int[]
getNonZeroValues()

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

int[]
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.

string
forHumans(int|array$syntax =null,bool$short =false,int$parts =-1,int$options =null)

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

string
__toString()

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

toDateInterval()

Return native DateInterval PHP object matching the current instance.

toPeriod(DateTimeInterface|string|int...$params)

Convert the interval to a CarbonPeriod.

$this
invert(bool|int$inverted =null)

Invert the interval.

solveNegativeInterval()

No description

$this
add(string|DateInterval$unit,int|float$value =1)

Add the passed interval to the current instance.

$this
sub(string|DateInterval$unit,int|float$value =1)

Subtract the passed interval to the current instance.

$this
subtract(string|DateInterval$unit,int|float$value =1)

Subtract the passed interval to the current instance.

$this
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)

Add given parameters to the current interval.

$this
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)

Add given parameters to the current interval.

$this
times(float|int$factor)

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.

$this
shares(float|int$divider)

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.

copyProperties(CarbonInterval$interval,$ignoreSign =false)

No description

$this
multiply(float|int$factor)

Multiply and cascade current instance by a given factor.

$this
divide(float|int$divider)

Divide and cascade current instance by a given divider.

static string
getDateIntervalSpec(DateInterval$interval,bool$microseconds =false)

Get the interval_spec string of a date interval.

string
spec(bool$microseconds =false)

Get the interval_spec string.

static int
compareDateIntervals(DateInterval$first,DateInterval$second)

Comparing 2 date intervals.

int
compare(DateInterval$interval)

Comparing with passed interval.

$this
cascade()

Convert overflowed values into bigger units.

hasNegativeValues()

No description

hasPositiveValues()

No description

float
total(string$unit)

Get amount of given unit equivalent to the interval.

bool
eq(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is equal to another

bool
equalTo(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is equal to another

bool
ne(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is not equal to another

bool
notEqualTo(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is not equal to another

bool
gt(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is greater (longer) than another

bool
greaterThan(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is greater (longer) than another

bool
gte(CarbonInterval|DateInterval|mixed$interval)

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

bool
greaterThanOrEqualTo(CarbonInterval|DateInterval|mixed$interval)

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

bool
lt(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is less (shorter) than another

bool
lessThan(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is less (shorter) than another

bool
lte(CarbonInterval|DateInterval|mixed$interval)

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

bool
lessThanOrEqualTo(CarbonInterval|DateInterval|mixed$interval)

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

bool
between(CarbonInterval|DateInterval|mixed$interval1,CarbonInterval|DateInterval|mixed$interval2,bool$equal =true)

Determines if the instance is between two others.

bool
betweenIncluded(CarbonInterval|DateInterval|mixed$interval1,CarbonInterval|DateInterval|mixed$interval2)

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

bool
betweenExcluded(CarbonInterval|DateInterval|mixed$interval1,CarbonInterval|DateInterval|mixed$interval2)

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

bool
isBetween(CarbonInterval|DateInterval|mixed$interval1,CarbonInterval|DateInterval|mixed$interval2,bool$equal =true)

Determines if the instance is between two others

$this
roundUnit(string$unit,float|int|string|DateInterval|null$precision =1,string$function ='round')

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

$this
floorUnit(string$unit,float|int|string|DateInterval|null$precision =1)

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

$this
ceilUnit(string$unit,float|int|string|DateInterval|null$precision =1)

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

$this
round(float|int|string|DateInterval|null$precision =1,string$function ='round')

Round the current instance second with given precision if specified.

$this
floor(float|int|string|DateInterval|null$precision =1)

Round the current instance second with given precision if specified.

$this
ceil(float|int|string|DateInterval|null$precision =1)

Ceil the current instance second with given precision if specified.

Details

inIntervalRoundingat line23
protected callRoundMethod(string$method,array$parameters)

Parameters

string $method
array $parameters

inIntervalRoundingat line38
protected roundWith($precision,$function)

Parameters

$precision
$function

inIntervalStepat line35
Closure getStep()

Get the dynamic step in use.

Return Value

Closure

inIntervalStepat line47
setStep(Closure|null$step)

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

Or pass null to switch to fixed interval.

Parameters

Closure|null $step

inIntervalStepat line62
CarbonInterface convertDate(DateTimeInterface$dateTime,bool$negated =false)

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

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

Parameters

DateTimeInterface $dateTime
bool $negated

Return Value

CarbonInterface

at line1292
staticvoid mixin(object|string$mixin)

Register macros from a mixin object.

Parameters

object|string $mixin

Return Value

void

Exceptions

ReflectionException

inMixinat line151
staticprotectedmixed bindMacroContext(Mixin|null$context,callable$callable)

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

Parameters

Mixin|null $context
callable $callable

Return Value

mixed

Exceptions

Throwable

inMixinat line177
staticprotectedMixin|null context()

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

Return Value

Mixin|null

at line681
staticprotectedCarbonInterval this()

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

Return Value

CarbonInterval

inLocalizationat line70
static setHumanDiffOptions(int$humanDiffOptions)deprecated

deprecated To avoid conflict between different third-party libraries, static setters should not be used. You should rather use the ->settings() method.

Parameters

int $humanDiffOptions

See also

settings

inLocalizationat line82
static enableHumanDiffOption(int$humanDiffOption)deprecated

deprecated To avoid conflict between different third-party libraries, static setters should not be used. You should rather use the ->settings() method.

Parameters

int $humanDiffOption

See also

settings

inLocalizationat line94
static disableHumanDiffOption(int$humanDiffOption)deprecated

deprecated To avoid conflict between different third-party libraries, static setters should not be used. You should rather use the ->settings() method.

Parameters

int $humanDiffOption

See also

settings

inLocalizationat line104
staticint getHumanDiffOptions()

Return default humanDiff() options (merged flags as integer).

Return Value

int

inLocalizationat line114
staticTranslatorInterface getTranslator()

Get the default translator instance in use.

Return Value

TranslatorInterface

inLocalizationat line126
staticvoid setTranslator(TranslatorInterface$translator)

Set the default translator instance to use.

Parameters

TranslatorInterface $translator

Return Value

void

inLocalizationat line136
bool hasLocalTranslator()

Return true if the current instance has its own translator.

Return Value

bool

inLocalizationat line146
TranslatorInterface getLocalTranslator()

Get the translator of the current instance or the default if none set.

Return Value

TranslatorInterface

inLocalizationat line158
$this setLocalTranslator(TranslatorInterface$translator)

Set the translator for the current instance.

Parameters

TranslatorInterface $translator

Return Value

$this

inLocalizationat line175
staticstring getTranslationMessageWith(TranslatorInterface$translator,string$key,string|null$locale =null,string|null$default =null)

Returns raw translation message for a given key.

Parameters

TranslatorInterface $translator the translator to use
string $key key to find
string|null $locale current locale used if null
string|null $default default value if translation returns the key

Return Value

string

inLocalizationat line203
string getTranslationMessage(string$key,string|null$locale =null,string|null$default =null,TranslatorInterface$translator =null)

Returns raw translation message for a given key.

Parameters

string $key key to find
string|null $locale current locale used if null
string|null $default default value if translation returns the key
TranslatorInterface $translator an optional translator to use

Return Value

string

inLocalizationat line218
staticstring translateWith(TranslatorInterface$translator,string$key,array$parameters =[],null$number =null)

Translate using translation string or callback available.

Parameters

TranslatorInterface $translator
string $key
array $parameters
null $number

Return Value

string

inLocalizationat line252
string translate(string$key,array$parameters =[],string|int|float|null$number =null,TranslatorInterface|null$translator =null,bool$altNumbers =false)

Translate using translation string or callback available.

Parameters

string $key
array $parameters
string|int|float|null $number
TranslatorInterface|null $translator
bool $altNumbers

Return Value

string

inLocalizationat line270
string translateNumber(int$number)

Returns the alternative number for a given integer if available in the current locale.

Parameters

int $number

Return Value

string

inLocalizationat line329
staticstring translateTimeString(string$timeString,string|null$from =null,string|null$to =null,int$mode =CarbonInterface::TRANSLATE_ALL)

Translate a time string from a locale to an other.

Parameters

string $timeString date/time/duration string to translate (may also contain English)
string|null $from input locale of the $timeString parameter (Carbon::getLocale() by default)
string|null $to output locale of the result returned ("en" by default)
int $mode specify what to translate with options: - CarbonInterface::TRANSLATE_ALL (default) - CarbonInterface::TRANSLATE_MONTHS - CarbonInterface::TRANSLATE_DAYS - CarbonInterface::TRANSLATE_UNITS - CarbonInterface::TRANSLATE_MERIDIEM You can use pipe to group: CarbonInterface::TRANSLATE_MONTHS | CarbonInterface::TRANSLATE_DAYS

Return Value

string

inLocalizationat line425
string translateTimeStringTo(string$timeString,string|null$to =null)

Translate a time string from the current locale ($date->locale()) to an other.

Parameters

string $timeString time string to translate
string|null $to output locale of the result returned ("en" by default)

Return Value

string

inLocalizationat line438
$this|string locale(string$locale =null,string...$fallbackLocales)

Get/set the locale for the current instance.

Parameters

string $locale
string ...$fallbackLocales

Return Value

$this|string

inLocalizationat line470
staticstring getLocale()

Get the current translator locale.

Return Value

string

inLocalizationat line483
staticbool setLocale(string$locale)

Set the current translator locale and indicate if the source locale file exists.

Pass 'auto' as locale to use closest language from the current LC_TIME locale.

Parameters

string $locale locale ex. en

Return Value

bool

inLocalizationat line495
static setFallbackLocale(string$locale)

Set the fallback locale.

inLocalizationat line520
staticstring|null getFallbackLocale()

Get the fallback locale.

inLocalizationat line540
staticmixed executeWithLocale(string$locale,callable$func)

Set the current locale to the given, execute the passed function, reset the locale to previous one, then return the result of the closure (or null if the closure was void).

Parameters

string $locale locale ex. en
callable $func

Return Value

mixed

inLocalizationat line557
staticbool localeHasShortUnits(string$locale)

Returns true if the given locale is internally supported and has short-units support.

Support is considered enabled if either year, day or hour has a short variant translated.

Parameters

string $locale locale ex. en

Return Value

bool

inLocalizationat line578
staticbool localeHasDiffSyntax(string$locale)

Returns true if the given locale is internally supported and has diff syntax support (ago, from now, before, after).

Support is considered enabled if the 4 sentences are translated in the given locale.

Parameters

string $locale locale ex. en

Return Value

bool

inLocalizationat line609
staticbool localeHasDiffOneDayWords(string$locale)

Returns true if the given locale is internally supported and has words for 1-day diff (just now, yesterday, tomorrow).

Support is considered enabled if the 3 words are translated in the given locale.

Parameters

string $locale locale ex. en

Return Value

bool

inLocalizationat line627
staticbool localeHasDiffTwoDayWords(string$locale)

Returns true if the given locale is internally supported and has words for 2-days diff (before yesterday, after tomorrow).

Support is considered enabled if the 2 words are translated in the given locale.

Parameters

string $locale locale ex. en

Return Value

bool

inLocalizationat line644
staticbool localeHasPeriodSyntax(string$locale)

Returns true if the given locale is internally supported and has period syntax support (X times, every X, from X, to X).

Support is considered enabled if the 4 sentences are translated in the given locale.

Parameters

string $locale locale ex. en

Return Value

bool

inLocalizationat line661
staticarray getAvailableLocales()

Returns the list of internally available locales and already loaded custom locales.

(It will ignore custom translator dynamic loading.)

Return Value

array

inLocalizationat line676
staticLanguage[] getAvailableLocalesInfo()

Returns list of Language object for each available locale. This object allow you to get the ISO name, native name, region and variant of the locale.

Return Value

Language[]

inLocalizationat line691
staticprotectedTranslatorInterface translator()

Initialize the default translator instance if necessary.

Return Value

TranslatorInterface

inLocalizationat line710
protectedstring|null getTranslatorLocale(null$translator =null)

Get the locale of a given translator.

If null or omitted, current local translator is used. If no local translator is in use, current global translator is used.

Parameters

null $translator

Return Value

string|null

inLocalizationat line728
staticprotectedLocaleAwareInterface|null getLocaleAwareTranslator(LocaleAwareInterface|null$translator =null)

Throw an error if passed object is not LocaleAwareInterface.

Parameters

LocaleAwareInterface|null $translator

Return Value

LocaleAwareInterface|null

inOptionsat line246
static useStrictMode(bool$strictModeEnabled =true)deprecated

deprecated To avoid conflict between different third-party libraries, static setters should not be used. You should rather use the ->settings() method.

Parameters

bool $strictModeEnabled

See also

settings Enable the strict mode (or disable with passing false).

inOptionsat line257
staticbool isStrictModeEnabled()

Returns true if the strict mode is globally in use, false else.

(It can be overridden in specific instances.)

Return Value

bool

inOptionsat line275
staticvoid useMonthsOverflow(bool$monthsOverflow =true)deprecated

deprecated To avoid conflict between different third-party libraries, static setters should not be used. You should rather use the ->settings() method. Or you can use method variants: addMonthsWithOverflow/addMonthsNoOverflow, same variants are available for quarters, years, decade, centuries, millennia (singular and plural forms).

Parameters

bool $monthsOverflow

Return Value

void

See also

settings Indicates if months should be calculated with overflow.

inOptionsat line291
staticvoid resetMonthsOverflow()deprecated

deprecated To avoid conflict between different third-party libraries, static setters should not be used. You should rather use the ->settings() method. Or you can use method variants: addMonthsWithOverflow/addMonthsNoOverflow, same variants are available for quarters, years, decade, centuries, millennia (singular and plural forms).

Return Value

void

See also

settings Reset the month overflow behavior.

inOptionsat line301
staticbool shouldOverflowMonths()

Get the month overflow global behavior (can be overridden in specific instances).

Return Value

bool

inOptionsat line319
staticvoid useYearsOverflow(bool$yearsOverflow =true)deprecated

deprecated To avoid conflict between different third-party libraries, static setters should not be used. You should rather use the ->settings() method. Or you can use method variants: addYearsWithOverflow/addYearsNoOverflow, same variants are available for quarters, years, decade, centuries, millennia (singular and plural forms).

Parameters

bool $yearsOverflow

Return Value

void

See also

settings Indicates if years should be calculated with overflow.

inOptionsat line335
staticvoid resetYearsOverflow()deprecated

deprecated To avoid conflict between different third-party libraries, static setters should not be used. You should rather use the ->settings() method. Or you can use method variants: addYearsWithOverflow/addYearsNoOverflow, same variants are available for quarters, years, decade, centuries, millennia (singular and plural forms).

Return Value

void

See also

settings Reset the month overflow behavior.

inOptionsat line345
staticbool shouldOverflowYears()

Get the month overflow global behavior (can be overridden in specific instances).

Return Value

bool

inOptionsat line367
$this|Options settings(array$settings)

Set specific options.

  • 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

array $settings

Return Value

$this|Options

inOptionsat line405
array getSettings()

Returns current local settings.

Return Value

array

inOptionsat line438
array __debugInfo()

Show truthy properties on var_dump().

Return Value

array

inOptionsat line455
protected addExtraDebugInfos($infos)

Parameters

$infos

at line281
CarbonInterval shiftTimezone(DateTimeZone|string$tzName)

Parameters

DateTimeZone|string $tzName

Return Value

CarbonInterval

at line265
CarbonInterval setTimezone(DateTimeZone|string$tzName)

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

Parameters

DateTimeZone|string $tzName

Return Value

CarbonInterval

at line295
staticarray getCascadeFactors()

Mapping of units and factors for cascading.

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

Return Value

array

at line334
static setCascadeFactors(array$cascadeFactors)

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

Parameters

array $cascadeFactors

at line358
__construct(Closure|DateInterval|string|int|null$years =1,int|null$months =null,int|null$weeks =null,int|null$days =null,int|null$hours =null,int|null$minutes =null,int|null$seconds =null,int|null$microseconds =null)

Create a new CarbonInterval instance.

Parameters

Closure|DateInterval|string|int|null $years
int|null $months
int|null $weeks
int|null $days
int|null $hours
int|null $minutes
int|null $seconds
int|null $microseconds

Exceptions

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

at line415
staticint|float|null getFactor(string$source,string$target)

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

Parameters

string $source
string $target

Return Value

int|float|null

at line443
staticint|float|null getFactorWithDefault(string$source,string$target)

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.

Parameters

string $source
string $target

Return Value

int|float|null

at line470
staticint|float getDaysPerWeek()

Returns current config for days per week.

Return Value

int|float

at line480
staticint|float getHoursPerDay()

Returns current config for hours per day.

Return Value

int|float

at line490
staticint|float getMinutesPerHour()

Returns current config for minutes per hour.

Return Value

int|float

at line500
staticint|float getSecondsPerMinute()

Returns current config for seconds per minute.

Return Value

int|float

at line510
staticint|float getMillisecondsPerSecond()

Returns current config for microseconds per second.

Return Value

int|float

at line520
staticint|float getMicrosecondsPerMillisecond()

Returns current config for microseconds per second.

Return Value

int|float

at line544
staticCarbonInterval create(int$years =1,int$months =null,int$weeks =null,int$days =null,int$hours =null,int$minutes =null,int$seconds =null,int$microseconds =null)

Create a new CarbonInterval instance from specific values.

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

int $years
int $months
int $weeks
int $days
int $hours
int $minutes
int $seconds
int $microseconds

Return Value

CarbonInterval

Exceptions

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

at line564
staticCarbonInterval createFromFormat(string$format,string|null$interval)

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

Parameters

string $format Format of the $interval input string
string|null $interval Input string to convert into an interval

Return Value

CarbonInterval

Exceptions

ParseErrorException when the $interval cannot be parsed as an interval.

at line621
CarbonInterval copy()

Get a copy of the instance.

Return Value

CarbonInterval

at line635
CarbonInterval clone()

Get a copy of the instance.

Return Value

CarbonInterval

at line651
staticCarbonInterval|null __callStatic(string$method,array$parameters)

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

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

Parameters

string $method magic method name called
array $parameters parameters list

Return Value

CarbonInterval|null

at line712
staticCarbonInterval fromString(string$intervalDefinition)

Creates a CarbonInterval from string.

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

string $intervalDefinition

Return Value

CarbonInterval

at line880
staticCarbonInterval parseFromLocale(string$interval,string|null$locale =null)

Creates a CarbonInterval from string using a different locale.

Parameters

string $interval interval string in the given language (may also contain English).
string|null $locale if locale is null or not specified, current global locale will be used instead.

Return Value

CarbonInterval

at line932
DateInterval cast(string$className)

Cast the current instance into the given class.

Parameters

string $className The $className::instance() method will be called to cast the current object.

Return Value

DateInterval

at line946
staticCarbonInterval instance(DateInterval$interval)

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.

Parameters

DateInterval $interval

Return Value

CarbonInterval

at line962
staticCarbonInterval|null make(mixed|int|DateInterval|string|Closure|null$interval,string|null$unit =null)

Make a CarbonInterval instance from given variable if possible.

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

mixed|int|DateInterval|string|Closure|null $interval interval or number of the given $unit
string|null $unit if specified, $interval must be an integer

Return Value

CarbonInterval|null

at line983
staticprotected makeFromString(string$interval)

Parameters

string $interval

at line1001
protected resolveInterval($interval)

Parameters

$interval

at line1020
static createFromDateString($time)

Parameters

$time

at line1047
int|float|string get(string$name)

Get a part of the CarbonInterval object.

Parameters

string $name

Return Value

int|float|string

Exceptions

UnknownGetterException

at line1107
int|float|string __get(string$name)

Get a part of the CarbonInterval object.

Parameters

string $name

Return Value

int|float|string

Exceptions

UnknownGetterException

at line1122
$this set(string|array$name,int$value =null)

Set a part of the CarbonInterval object.

Parameters

string|array $name
int $value

Return Value

$this

Exceptions

UnknownSetterException

at line1201
__set(string$name,int$value)

Set a part of the CarbonInterval object.

Parameters

string $name
int $value

Exceptions

UnknownSetterException

at line1214
CarbonInterval weeksAndDays(int$weeks,int$days)

Allow setting of weeks and days to be cumulative.

Parameters

int $weeks Number of weeks to set
int $days Number of days to set

Return Value

CarbonInterval

at line1226
bool isEmpty()

Returns true if the interval is empty for each unit.

Return Value

bool

at line1254
staticvoid macro(string$name,object|callable$macro)

Register a custom macro.

Parameters

string $name
object|callable $macro

Return Value

void

at line1304
staticbool hasMacro(string$name)

Check if macro is registered.

Parameters

string $name

Return Value

bool

at line1317
protectedmixed callMacro(string$name,array$parameters)

Call given macro.

Parameters

string $name
array $parameters

Return Value

mixed

at line1343
CarbonInterval __call(string$method,array$parameters)

Allow fluent calls on the setters.

.. CarbonInterval::years(3)->months(5)->day().

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

Parameters

string $method magic method name called
array $parameters parameters list

Return Value

CarbonInterval

Exceptions

Throwable

at line1372
protected getForHumansInitialVariables($syntax,$short)

Parameters

$syntax
$short

at line1403
protectedarray getForHumansParameters(mixed$syntax =null,mixed$short =false,mixed$parts =-1,mixed$options =null)

Parameters

mixed $syntax
mixed $short
mixed $parts
mixed $options

Return Value

array

at line1479
staticprotected getRoundingMethodFromOptions(int$options)

Parameters

int $options

at line1501
int[] toArray()

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

Return Value

int[]

at line1520
int[] getNonZeroValues()

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

Return Value

int[]

at line1531
int[] 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.

Return Value

int[]

at line1607
string forHumans(int|array$syntax =null,bool$short =false,int$parts =-1,int$options =null)

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

Parameters

int|array $syntax if array passed, parameters will be extracted from it, the array may contains: - '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 - '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) if int passed, it add 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
bool $short displays short format of time units
int $parts maximum number of parts to display (default value: -1: no limits)
int $options human diff options

Return Value

string

Exceptions

Exception

at line1822
string __toString()

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

Return Value

string

Exceptions

Exception

at line1847
DateInterval toDateInterval()

Return native DateInterval PHP object matching the current instance.

Return Value

DateInterval

at line1859
CarbonPeriod toPeriod(DateTimeInterface|string|int...$params)

Convert the interval to a CarbonPeriod.

Parameters

DateTimeInterface|string|int ...$params Start date, [end date or recurrences] and optional settings.

Return Value

CarbonPeriod

at line1880
$this invert(bool|int$inverted =null)

Invert the interval.

Parameters

bool|int $inverted if a parameter is passed, the passed value casted as 1 or 0 is used as the new value of the ->invert property.

Return Value

$this

at line1887
protected solveNegativeInterval()

at line1911
$this add(string|DateInterval$unit,int|float$value =1)

Add the passed interval to the current instance.

Parameters

string|DateInterval $unit
int|float $value

Return Value

$this

at line1954
$this sub(string|DateInterval$unit,int|float$value =1)

Subtract the passed interval to the current instance.

Parameters

string|DateInterval $unit
int|float $value

Return Value

$this

at line1971
$this subtract(string|DateInterval$unit,int|float$value =1)

Subtract the passed interval to the current instance.

Parameters

string|DateInterval $unit
int|float $value

Return Value

$this

at line1990
$this 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)

Add given parameters to the current interval.

Parameters

int $years
int $months
int|float $weeks
int|float $days
int|float $hours
int|float $minutes
int|float $seconds
int|float $microseconds

Return Value

$this

at line2020
$this 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)

Add given parameters to the current interval.

Parameters

int $years
int $months
int|float $weeks
int|float $days
int|float $hours
int|float $minutes
int|float $seconds
int|float $microseconds

Return Value

$this

at line2051
$this times(float|int$factor)

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.

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

For a precise and cascaded calculation,

Parameters

float|int $factor

Return Value

$this

See also

multiply()

at line2084
$this shares(float|int$divider)

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.

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

For a precise and cascaded calculation,

Parameters

float|int $divider

Return Value

$this

See also

divide()

at line2089
protected copyProperties(CarbonInterval$interval,$ignoreSign =false)

Parameters

CarbonInterval $interval
$ignoreSign

at line2113
$this multiply(float|int$factor)

Multiply and cascade current instance by a given factor.

Parameters

float|int $factor

Return Value

$this

at line2141
$this divide(float|int$divider)

Divide and cascade current instance by a given divider.

Parameters

float|int $divider

Return Value

$this

at line2153
staticstring getDateIntervalSpec(DateInterval$interval,bool$microseconds =false)

Get the interval_spec string of a date interval.

Parameters

DateInterval $interval
bool $microseconds

Return Value

string

at line2193
string spec(bool$microseconds =false)

Get the interval_spec string.

Parameters

bool $microseconds

Return Value

string

at line2206
staticint compareDateIntervals(DateInterval$first,DateInterval$second)

Comparing 2 date intervals.

Parameters

DateInterval $first
DateInterval $second

Return Value

int

at line2229
int compare(DateInterval$interval)

Comparing with passed interval.

Parameters

DateInterval $interval

Return Value

int

at line2313
$this cascade()

Convert overflowed values into bigger units.

Return Value

$this

at line2318
hasNegativeValues()

at line2329
hasPositiveValues()

at line2349
float total(string$unit)

Get amount of given unit equivalent to the interval.

Parameters

string $unit

Return Value

float

Exceptions

UnitNotConfiguredException

at line2446
bool eq(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is equal to another

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

See also

equalTo()

at line2458
bool equalTo(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is equal to another

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

at line2474
bool ne(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is not equal to another

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

See also

notEqualTo()

at line2486
bool notEqualTo(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is not equal to another

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

at line2500
bool gt(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is greater (longer) than another

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

See also

greaterThan()

at line2512
bool greaterThan(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is greater (longer) than another

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

at line2528
bool gte(CarbonInterval|DateInterval|mixed$interval)

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

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

See also

greaterThanOrEqualTo()

at line2540
bool greaterThanOrEqualTo(CarbonInterval|DateInterval|mixed$interval)

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

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

at line2554
bool lt(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is less (shorter) than another

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

See also

lessThan()

at line2566
bool lessThan(CarbonInterval|DateInterval|mixed$interval)

Determines if the instance is less (shorter) than another

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

at line2582
bool lte(CarbonInterval|DateInterval|mixed$interval)

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

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

See also

lessThanOrEqualTo()

at line2594
bool lessThanOrEqualTo(CarbonInterval|DateInterval|mixed$interval)

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

Parameters

CarbonInterval|DateInterval|mixed $interval

Return Value

bool

at line2620
bool between(CarbonInterval|DateInterval|mixed$interval1,CarbonInterval|DateInterval|mixed$interval2,bool$equal =true)

Determines if the instance is between two others.

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

CarbonInterval|DateInterval|mixed $interval1
CarbonInterval|DateInterval|mixed $interval2
bool $equal Indicates if an equal to comparison should be done

Return Value

bool

at line2642
bool betweenIncluded(CarbonInterval|DateInterval|mixed$interval1,CarbonInterval|DateInterval|mixed$interval2)

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

Parameters

CarbonInterval|DateInterval|mixed $interval1
CarbonInterval|DateInterval|mixed $interval2

Return Value

bool

at line2662
bool betweenExcluded(CarbonInterval|DateInterval|mixed$interval1,CarbonInterval|DateInterval|mixed$interval2)

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

Parameters

CarbonInterval|DateInterval|mixed $interval1
CarbonInterval|DateInterval|mixed $interval2

Return Value

bool

at line2684
bool isBetween(CarbonInterval|DateInterval|mixed$interval1,CarbonInterval|DateInterval|mixed$interval2,bool$equal =true)

Determines if the instance is between two others

Parameters

CarbonInterval|DateInterval|mixed $interval1
CarbonInterval|DateInterval|mixed $interval2
bool $equal Indicates if an equal to comparison should be done

Return Value

bool

at line2700
$this roundUnit(string$unit,float|int|string|DateInterval|null$precision =1,string$function ='round')

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

Parameters

string $unit
float|int|string|DateInterval|null $precision
string $function

Return Value

$this

Exceptions

Exception

at line2730
$this floorUnit(string$unit,float|int|string|DateInterval|null$precision =1)

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

Parameters

string $unit
float|int|string|DateInterval|null $precision

Return Value

$this

Exceptions

Exception

at line2745
$this ceilUnit(string$unit,float|int|string|DateInterval|null$precision =1)

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

Parameters

string $unit
float|int|string|DateInterval|null $precision

Return Value

$this

Exceptions

Exception

at line2760
$this round(float|int|string|DateInterval|null$precision =1,string$function ='round')

Round the current instance second with given precision if specified.

Parameters

float|int|string|DateInterval|null $precision
string $function

Return Value

$this

Exceptions

Exception

at line2774
$this floor(float|int|string|DateInterval|null$precision =1)

Round the current instance second with given precision if specified.

Parameters

float|int|string|DateInterval|null $precision

Return Value

$this

Exceptions

Exception

at line2788
$this ceil(float|int|string|DateInterval|null$precision =1)

Ceil the current instance second with given precision if specified.

Parameters

float|int|string|DateInterval|null $precision

Return Value

$this

Exceptions

Exception