class CarbonPeriod implementsIterator,Countable,JsonSerializable

Substitution of DatePeriod with some modifications and many more features.

Traits

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

Constants

RECURRENCES_FILTER

Built-in filter for limit by recurrences.

END_DATE_FILTER

Built-in filter for limit to an end.

END_ITERATION

Special value which can be returned by filters to end iteration. Also a filter.

EXCLUDE_START_DATE

Exclude start date from iteration.

EXCLUDE_END_DATE

Exclude end date from iteration.

IMMUTABLE

Yield CarbonImmutable instances.

NEXT_MAX_ATTEMPTS

Number of maximum attempts before giving up on finding next valid date.

END_MAX_ATTEMPTS

Number of maximum attempts before giving up on finding end date.

Properties

staticprotectedarray $macroContextStack Stack of macro instance contexts. from Mixin
staticprotectedTranslatorInterface $translator Default translator. from Localization
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 $macros The registered macros.
protectedstring $dateClass Date class of iteration items.
protectedCarbonInterval $dateInterval Underlying date interval instance. Always present, one day by default.
protectedbool $isDefaultInterval Whether current date interval was set by default.
protectedarray $filters The filters stack.
protectedCarbonInterface $startDate Period start date. Applied on rewind. Always present, now by default.
protectedCarbonInterface|null $endDate Period end date. For inverted interval should be before the start date. Applied via a filter.
protectedint|null $recurrences Limit for number of recurrences. Applied via a filter.
protectedint $options Iteration options.
protectedint $key Index of current date. Always sequential, even if some dates are skipped by filters.
protectedCarbonInterface $current Current date. May temporarily hold unaccepted value when looking for a next valid date.
protectedDateTimeZone|null $timezone Timezone of current date. Taken from the start date.
protectedbool|string|null $validationResult The cached validation result for current date.
protectedmixed $tzName Timezone handler for settings() method.

Methods

callRoundMethod(string$method,array$parameters)

No description

roundWith($precision,$function)

No description

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
static Mixin
this()

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

from Mixin
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$timezone)

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

static CarbonPeriod|null
make(mixed$var)

Make a CarbonPeriod instance from given variable if possible.

static CarbonPeriod
instance(CarbonPeriod|DatePeriod$period)

Create a new instance from a DatePeriod or CarbonPeriod object.

static CarbonPeriod
create(...$params)

Create a new instance.

static CarbonPeriod
createFromArray(array$params)

Create a new instance from an array of parameters.

static CarbonPeriod
createFromIso(string$iso,int|null$options =null)

Create CarbonPeriod from ISO 8601 string.

static bool
intervalHasTime(DateInterval$interval)

Return whether given interval contains non zero value of any time unit.

static bool
isIso8601(mixed$var)

Return whether given variable is an ISO 8601 specification.

static array
parseIso8601(string$iso)

Parse given ISO 8601 string into an array of arguments.

static string
addMissingParts(string$source,string$target)

Add missing parts of the target date from the soure date.

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

Register a custom macro.

static bool
hasMacro(string$name)

Check if macro is registered.

static mixed
__callStatic(string$method,array$parameters)

Provide static proxy for instance aliases.

__construct(...$arguments)

CarbonPeriod constructor.

copy()

Get a copy of the instance.

callable|null
getGetter(string$name)

Get the getter for a property allowing both DatePeriod snakeCase and camelCase names.

get(string$name)

Get a property allowing both DatePeriod snakeCase and camelCase names.

__get(string$name)

Get a property allowing both DatePeriod snakeCase and camelCase names.

bool
__isset(string$name)

Check if an attribute exists on the object

clone()

No description

$this
setDateClass(string$dateClass)

Set the iteration item class.

string
getDateClass()

Returns iteration item date class.

$this
setDateInterval(DateInterval|string$interval)

Change the period date interval.

$this
invertDateInterval()

Invert the period date interval.

$this
setDates(DateTime|DateTimeInterface|string$start,DateTime|DateTimeInterface|string|null$end)

Set start and end date.

$this
setOptions(int|null$options)

Change the period options.

int
getOptions()

Get the period options.

$this
toggleOptions(int$options,bool|null$state =null)

Toggle given options on or off.

$this
excludeStartDate(bool$state =true)

Toggle EXCLUDE_START_DATE option.

$this
excludeEndDate(bool$state =true)

Toggle EXCLUDE_END_DATE option.

getDateInterval()

Get the underlying date interval.

getStartDate(string$rounding =null)

Get start date of the period.

getEndDate(string$rounding =null)

Get end date of the period.

int|float|null
getRecurrences()

Get number of recurrences.

bool
isStartExcluded()

Returns true if the start date should be excluded.

bool
isEndExcluded()

Returns true if the end date should be excluded.

bool
isStartIncluded()

Returns true if the start date should be included.

bool
isEndIncluded()

Returns true if the end date should be included.

getIncludedStartDate()

Return the start if it's included by option, else return the start + 1 period interval.

getIncludedEndDate()

Return the end if it's included by option, else return the end - 1 period interval.

$this
addFilter(callable$callback,string$name =null)

Add a filter to the stack.

$this
prependFilter(callable$callback,string$name =null)

Prepend a filter to the stack.

$this
removeFilter(callable|string$filter)

Remove a filter by instance or name.

bool
hasFilter(callable|string$filter)

Return whether given instance or name is in the filter stack.

array
getFilters()

Get filters stack.

$this
setFilters(array$filters)

Set filters stack.

$this
resetFilters()

Reset filters stack.

$this
setRecurrences(int|float|null$recurrences)

Add a recurrences filter (set maximum number of recurrences).

$this
setStartDate(DateTime|DateTimeInterface|string$date,bool|null$inclusive =null)

Change the period start date.

$this
setEndDate(DateTime|DateTimeInterface|string|null$date,bool|null$inclusive =null)

Change the period end date.

valid()

No description

key()

No description

current()

No description

next()

No description

rewind()

No description

bool
skip(int$count =1)

Skip iterations and returns iteration state (false if ended, true if still valid).

string
toIso8601String()

Format the date period as ISO 8601.

string
toString()

Convert the date period into a string.

string
spec()

Format the date period as ISO 8601.

cast(string$className)

Cast the current instance into the given class.

toDatePeriod()

Return native DatePeriod PHP object matching the current instance.

isUnfilteredAndEndLess()

Return true if the period has no custom filter and is guaranteed to be endless.

toArray()

Convert the date period into an array without changing current iteration state.

count()

No description

first()

Return the first date in the date period.

last()

Return the last date in the date period.

string
__toString()

Convert the date period into a string.

mixed
__call(string$method,array$parameters)

Add aliases for setters.

setTimezone(DateTimeZone|string$timezone)

Set the instance's timezone from a string or object and apply it to start/end.

calculateEnd(string$rounding =null)

Returns the end is set, else calculated from start an recurrences.

bool
overlaps(CarbonPeriod|DateTimeInterface|Carbon|CarbonImmutable|string$rangeOrRangeStart,DateTimeInterface|Carbon|CarbonImmutable|string|null$rangeEnd =null)

Returns true if the current period overlaps the given one (if 1 parameter passed) or the period between 2 dates (if 2 parameters passed).

forEach(callable$callback)

Execute a given function on each date of the period.

map(callable$callback)

Execute a given function on each date of the period and yield the result of this function.

bool
eq(mixed$period)

Determines if the instance is equal to another.

bool
equalTo(mixed$period)

Determines if the instance is equal to another.

bool
ne(mixed$period)

Determines if the instance is not equal to another.

bool
notEqualTo(mixed$period)

Determines if the instance is not equal to another.

bool
startsBefore(mixed$date =null)

Determines if the start date is before an other given date.

bool
startsBeforeOrAt(mixed$date =null)

Determines if the start date is before or the same as a given date.

bool
startsAfter(mixed$date =null)

Determines if the start date is after an other given date.

bool
startsAfterOrAt(mixed$date =null)

Determines if the start date is after or the same as a given date.

bool
startsAt(mixed$date =null)

Determines if the start date is the same as a given date.

bool
endsBefore(mixed$date =null)

Determines if the end date is before an other given date.

bool
endsBeforeOrAt(mixed$date =null)

Determines if the end date is before or the same as a given date.

bool
endsAfter(mixed$date =null)

Determines if the end date is after an other given date.

bool
endsAfterOrAt(mixed$date =null)

Determines if the end date is after or the same as a given date.

bool
endsAt(mixed$date =null)

Determines if the end date is the same as a given date.

bool
isStarted()

Return true if start date is now or later.

bool
isEnded()

Return true if end date is now or later.

bool
isInProgress()

Return true if now is between start date (included) and end date (excluded).

$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 =null,string$function ='round')

Round the current instance second with given precision if specified (else period interval is used).

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

Round the current instance second with given precision if specified (else period interval is used).

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

Ceil the current instance second with given precision if specified (else period interval is used).

jsonSerialize()

No description

bool
contains(Carbon|CarbonPeriod|CarbonInterval|DateInterval|DatePeriod|DateTimeInterface|string|null$date =null)

Return true if the given date is between start and end.

bool
follows($period,...$arguments)

Return true if the current period follows a given other period (with no overlap).

bool
isFollowedBy($period,...$arguments)

Return true if the given other period follows the current one (with no overlap).

bool
isConsecutiveWith($period,...$arguments)

Return true if the given period either follows or is followed by the current one.

void
updateInternalState()

Update properties after removing built-in filters.

array
createFilterTuple(array$parameters)

Create a filter tuple from raw parameters.

bool
isCarbonPredicateMethod(callable$callable)

Return whether given callable is a string pointing to one of Carbon's is* methods and should be automatically converted to a filter callback.

bool|string
filterRecurrences(Carbon$current,int$key)

Recurrences filter callback (limits number of recurrences).

bool|string
filterEndDate(Carbon$current)

End date filter callback.

string
endIteration()

End iteration filter callback.

handleChangedParameters()

Handle change of the parameters.

bool|string
validateCurrentDate()

Validate current date and stop iteration when necessary.

bool|string
checkFilters()

Check whether current value and key pass all the filters.

prepareForReturn(CarbonInterface$date)

Prepare given date to be returned to the external logic.

void
incrementCurrentDateUntilValid()

Keep incrementing the current date until a valid date is found or the iteration is ended.

mixed
callMacro(string$name,array$parameters)

Call given macro.

resolveCarbon(Carbon|CarbonPeriod|CarbonInterval|DateInterval|DatePeriod|DateTimeInterface|string|null$date =null)

Return the Carbon instance passed through, a now instance in the same timezone if null given or parse the input if string given.

resolveCarbonPeriod(mixed$period,mixed...$arguments)

Resolve passed arguments or DatePeriod to a CarbonPeriod object.

Details

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

Parameters

string $method
array $parameters

inIntervalRoundingat line38
protected roundWith($precision,$function)

Parameters

$precision
$function

at line579
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

inMixinat line187
staticprotectedMixin this()

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

Return Value

Mixin

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 line1790
CarbonPeriod shiftTimezone(DateTimeZone|string$timezone)

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

Parameters

DateTimeZone|string $timezone

Return Value

CarbonPeriod

at line342
staticCarbonPeriod|null make(mixed$var)

Make a CarbonPeriod instance from given variable if possible.

Parameters

mixed $var

Return Value

CarbonPeriod|null

at line358
staticCarbonPeriod instance(CarbonPeriod|DatePeriod$period)

Create a new instance from a DatePeriod or CarbonPeriod object.

Parameters

CarbonPeriod|DatePeriod $period

Return Value

CarbonPeriod

at line397
staticCarbonPeriod create(...$params)

Create a new instance.

Parameters

...$params

Return Value

CarbonPeriod

at line409
staticCarbonPeriod createFromArray(array$params)

Create a new instance from an array of parameters.

Parameters

array $params

Return Value

CarbonPeriod

at line422
staticCarbonPeriod createFromIso(string$iso,int|null$options =null)

Create CarbonPeriod from ISO 8601 string.

Parameters

string $iso
int|null $options

Return Value

CarbonPeriod

at line442
staticprotectedbool intervalHasTime(DateInterval$interval)

Return whether given interval contains non zero value of any time unit.

Parameters

DateInterval $interval

Return Value

bool

at line457
staticprotectedbool isIso8601(mixed$var)

Return whether given variable is an ISO 8601 specification.

Note: Check is very basic, as actual validation will be done later when parsing. We just want to ensure that variable is not any other type of a valid parameter.

Parameters

mixed $var

Return Value

bool

at line480
staticprotectedarray parseIso8601(string$iso)

Parse given ISO 8601 string into an array of arguments.

Parameters

string $iso

Return Value

array

at line515
staticprotectedstring addMissingParts(string$source,string$target)

Add missing parts of the target date from the soure date.

Parameters

string $source
string $target

Return Value

string

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

Register a custom macro.

Parameters

string $name
object|callable $macro

Return Value

void

at line591
staticbool hasMacro(string$name)

Check if macro is registered.

Parameters

string $name

Return Value

bool

at line604
staticmixed __callStatic(string$method,array$parameters)

Provide static proxy for instance aliases.

Parameters

string $method
array $parameters

Return Value

mixed

at line624
__construct(...$arguments)

CarbonPeriod constructor.

Parameters

...$arguments

Exceptions

InvalidArgumentException

at line703
CarbonPeriod copy()

Get a copy of the instance.

Return Value

CarbonPeriod

at line715
protectedcallable|null getGetter(string$name)

Get the getter for a property allowing both DatePeriod snakeCase and camelCase names.

Parameters

string $name

Return Value

callable|null

at line747
bool|CarbonInterface|CarbonInterval|int|null get(string$name)

Get a property allowing both DatePeriod snakeCase and camelCase names.

Parameters

string $name

Return Value

bool|CarbonInterface|CarbonInterval|int|null

at line765
bool|CarbonInterface|CarbonInterval|int|null __get(string$name)

Get a property allowing both DatePeriod snakeCase and camelCase names.

Parameters

string $name

Return Value

bool|CarbonInterface|CarbonInterval|int|null

at line777
bool __isset(string$name)

Check if an attribute exists on the object

Parameters

string $name

Return Value

bool

at line789
CarbonPeriod clone()

Return Value

CarbonPeriod

at line801
$this setDateClass(string$dateClass)

Set the iteration item class.

Parameters

string $dateClass

Return Value

$this

at line823
string getDateClass()

Returns iteration item date class.

Return Value

string

at line837
$this setDateInterval(DateInterval|string$interval)

Change the period date interval.

Parameters

DateInterval|string $interval

Return Value

$this

Exceptions

InvalidIntervalException

at line861
$this invertDateInterval()

Invert the period date interval.

Return Value

$this

at line876
$this setDates(DateTime|DateTimeInterface|string$start,DateTime|DateTimeInterface|string|null$end)

Set start and end date.

Parameters

DateTime|DateTimeInterface|string $start
DateTime|DateTimeInterface|string|null $end

Return Value

$this

at line893
$this setOptions(int|null$options)

Change the period options.

Parameters

int|null $options

Return Value

$this

Exceptions

InvalidArgumentException

at line911
int getOptions()

Get the period options.

Return Value

int

at line926
$this toggleOptions(int$options,bool|null$state =null)

Toggle given options on or off.

Parameters

int $options
bool|null $state

Return Value

$this

Exceptions

InvalidArgumentException

at line946
$this excludeStartDate(bool$state =true)

Toggle EXCLUDE_START_DATE option.

Parameters

bool $state

Return Value

$this

at line958
$this excludeEndDate(bool$state =true)

Toggle EXCLUDE_END_DATE option.

Parameters

bool $state

Return Value

$this

at line968
CarbonInterval getDateInterval()

Get the underlying date interval.

Return Value

CarbonInterval

at line980
CarbonInterface getStartDate(string$rounding =null)

Get start date of the period.

Parameters

string $rounding Optional rounding 'floor', 'ceil', 'round' using the period interval.

Return Value

CarbonInterface

at line994
CarbonInterface|null getEndDate(string$rounding =null)

Get end date of the period.

Parameters

string $rounding Optional rounding 'floor', 'ceil', 'round' using the period interval.

Return Value

CarbonInterface|null

at line1010
int|float|null getRecurrences()

Get number of recurrences.

Return Value

int|float|null

at line1020
bool isStartExcluded()

Returns true if the start date should be excluded.

Return Value

bool

at line1030
bool isEndExcluded()

Returns true if the end date should be excluded.

Return Value

bool

at line1040
bool isStartIncluded()

Returns true if the start date should be included.

Return Value

bool

at line1050
bool isEndIncluded()

Returns true if the end date should be included.

Return Value

bool

at line1060
CarbonInterface getIncludedStartDate()

Return the start if it's included by option, else return the start + 1 period interval.

Return Value

CarbonInterface

at line1077
CarbonInterface getIncludedEndDate()

Return the end if it's included by option, else return the end - 1 period interval.

Warning: if the period has no fixed end, this method will iterate the period to calculate it.

Return Value

CarbonInterface

at line1102
$this addFilter(callable$callback,string$name =null)

Add a filter to the stack.

Parameters

callable $callback
string $name

Return Value

$this

at line1123
$this prependFilter(callable$callback,string$name =null)

Prepend a filter to the stack.

Parameters

callable $callback
string $name

Return Value

$this

at line1141
$this removeFilter(callable|string$filter)

Remove a filter by instance or name.

Parameters

callable|string $filter

Return Value

$this

at line1166
bool hasFilter(callable|string$filter)

Return whether given instance or name is in the filter stack.

Parameters

callable|string $filter

Return Value

bool

at line1184
array getFilters()

Get filters stack.

Return Value

array

at line1196
$this setFilters(array$filters)

Set filters stack.

Parameters

array $filters

Return Value

$this

at line1212
$this resetFilters()

Reset filters stack.

Return Value

$this

at line1238
$this setRecurrences(int|float|null$recurrences)

Add a recurrences filter (set maximum number of recurrences).

Parameters

int|float|null $recurrences

Return Value

$this

Exceptions

InvalidArgumentException

at line1269
$this setStartDate(DateTime|DateTimeInterface|string$date,bool|null$inclusive =null)

Change the period start date.

Parameters

DateTime|DateTimeInterface|string $date
bool|null $inclusive

Return Value

$this

Exceptions

InvalidPeriodDateException

at line1294
$this setEndDate(DateTime|DateTimeInterface|string|null$date,bool|null$inclusive =null)

Change the period end date.

Parameters

DateTime|DateTimeInterface|string|null $date
bool|null $inclusive

Return Value

$this

Exceptions

InvalidArgumentException

at line1325
valid()

at line1336
key()

at line1349
current()

at line1364
next()

at line1391
rewind()

at line1422
bool skip(int$count =1)

Skip iterations and returns iteration state (false if ended, true if still valid).

Parameters

int $count steps number to skip (1 by default)

Return Value

bool

at line1436
string toIso8601String()

Format the date period as ISO 8601.

Return Value

string

at line1460
string toString()

Convert the date period into a string.

Return Value

string

at line1494
string spec()

Format the date period as ISO 8601.

Return Value

string

at line1506
DatePeriod 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

DatePeriod

at line1534
DatePeriod toDatePeriod()

Return native DatePeriod PHP object matching the current instance.

Return Value

DatePeriod

at line1546
isUnfilteredAndEndLess()

Return true if the period has no custom filter and is guaranteed to be endless.

Note that we can't check if a period is endless as soon as it has custom filters because filters can emit CarbonPeriod::END_ITERATION to stop the iteration in a way we can't predict without actually iterating the period.

at line1577
CarbonInterface[] toArray()

Convert the date period into an array without changing current iteration state.

Return Value

CarbonInterface[]

at line1602
count()

at line1612
CarbonInterface|null first()

Return the first date in the date period.

Return Value

CarbonInterface|null

at line1632
CarbonInterface|null last()

Return the last date in the date period.

Return Value

CarbonInterface|null

at line1644
string __toString()

Convert the date period into a string.

Return Value

string

at line1664
mixed __call(string$method,array$parameters)

Add aliases for setters.

CarbonPeriod::days(3)->hours(5)->invert() ->sinceNow()->until('2010-01-10') ->filter(...) ->count()

Note: We use magic method to let static and instance aliases with the same names.

Parameters

string $method
array $parameters

Return Value

mixed

at line1767
CarbonPeriod setTimezone(DateTimeZone|string$timezone)

Set the instance's timezone from a string or object and apply it to start/end.

Parameters

DateTimeZone|string $timezone

Return Value

CarbonPeriod

at line1813
CarbonInterface calculateEnd(string$rounding =null)

Returns the end is set, else calculated from start an recurrences.

Parameters

string $rounding Optional rounding 'floor', 'ceil', 'round' using the period interval.

Return Value

CarbonInterface

at line1891
bool overlaps(CarbonPeriod|DateTimeInterface|Carbon|CarbonImmutable|string$rangeOrRangeStart,DateTimeInterface|Carbon|CarbonImmutable|string|null$rangeEnd =null)

Returns true if the current period overlaps the given one (if 1 parameter passed) or the period between 2 dates (if 2 parameters passed).

Parameters

CarbonPeriod|DateTimeInterface|Carbon|CarbonImmutable|string $rangeOrRangeStart
DateTimeInterface|Carbon|CarbonImmutable|string|null $rangeEnd

Return Value

bool

at line1917
forEach(callable$callback)

Execute a given function on each date of the period.

Parameters

callable $callback

at line1939
Generator map(callable$callback)

Execute a given function on each date of the period and yield the result of this function.

Parameters

callable $callback

Return Value

Generator

at line1956
bool eq(mixed$period)

Determines if the instance is equal to another.

Warning: if options differ, instances wil never be equal.

Parameters

mixed $period

Return Value

bool

See also

equalTo()

at line1969
bool equalTo(mixed$period)

Determines if the instance is equal to another.

Warning: if options differ, instances wil never be equal.

Parameters

mixed $period

Return Value

bool

at line1994
bool ne(mixed$period)

Determines if the instance is not equal to another.

Warning: if options differ, instances wil never be equal.

Parameters

mixed $period

Return Value

bool

See also

notEqualTo()

at line2007
bool notEqualTo(mixed$period)

Determines if the instance is not equal to another.

Warning: if options differ, instances wil never be equal.

Parameters

mixed $period

Return Value

bool

at line2020
bool startsBefore(mixed$date =null)

Determines if the start date is before an other given date.

(Rather start/end are included by options is ignored.)

Parameters

mixed $date

Return Value

bool

at line2033
bool startsBeforeOrAt(mixed$date =null)

Determines if the start date is before or the same as a given date.

(Rather start/end are included by options is ignored.)

Parameters

mixed $date

Return Value

bool

at line2046
bool startsAfter(mixed$date =null)

Determines if the start date is after an other given date.

(Rather start/end are included by options is ignored.)

Parameters

mixed $date

Return Value

bool

at line2059
bool startsAfterOrAt(mixed$date =null)

Determines if the start date is after or the same as a given date.

(Rather start/end are included by options is ignored.)

Parameters

mixed $date

Return Value

bool

at line2072
bool startsAt(mixed$date =null)

Determines if the start date is the same as a given date.

(Rather start/end are included by options is ignored.)

Parameters

mixed $date

Return Value

bool

at line2085
bool endsBefore(mixed$date =null)

Determines if the end date is before an other given date.

(Rather start/end are included by options is ignored.)

Parameters

mixed $date

Return Value

bool

at line2098
bool endsBeforeOrAt(mixed$date =null)

Determines if the end date is before or the same as a given date.

(Rather start/end are included by options is ignored.)

Parameters

mixed $date

Return Value

bool

at line2111
bool endsAfter(mixed$date =null)

Determines if the end date is after an other given date.

(Rather start/end are included by options is ignored.)

Parameters

mixed $date

Return Value

bool

at line2124
bool endsAfterOrAt(mixed$date =null)

Determines if the end date is after or the same as a given date.

(Rather start/end are included by options is ignored.)

Parameters

mixed $date

Return Value

bool

at line2137
bool endsAt(mixed$date =null)

Determines if the end date is the same as a given date.

(Rather start/end are included by options is ignored.)

Parameters

mixed $date

Return Value

bool

at line2148
bool isStarted()

Return true if start date is now or later.

(Rather start/end are included by options is ignored.)

Return Value

bool

at line2159
bool isEnded()

Return true if end date is now or later.

(Rather start/end are included by options is ignored.)

Return Value

bool

at line2170
bool isInProgress()

Return true if now is between start date (included) and end date (excluded).

(Rather start/end are included by options is ignored.)

Return Value

bool

at line2184
$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

at line2205
$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

at line2218
$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

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

Round the current instance second with given precision if specified (else period interval is used).

Parameters

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

Return Value

$this

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

Round the current instance second with given precision if specified (else period interval is used).

Parameters

float|int|string|DateInterval|null $precision

Return Value

$this

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

Ceil the current instance second with given precision if specified (else period interval is used).

Parameters

float|int|string|DateInterval|null $precision

Return Value

$this

at line2271
jsonSerialize()

at line2283
bool contains(Carbon|CarbonPeriod|CarbonInterval|DateInterval|DatePeriod|DateTimeInterface|string|null$date =null)

Return true if the given date is between start and end.

Parameters

Carbon|CarbonPeriod|CarbonInterval|DateInterval|DatePeriod|DateTimeInterface|string|null $date

Return Value

bool

at line2300
bool follows($period,...$arguments)

Return true if the current period follows a given other period (with no overlap).

For instance, [2019-08-01 -> 2019-08-12] follows [2019-07-29 -> 2019-07-31] Note than in this example, follows() would be false if 2019-08-01 or 2019-07-31 was excluded by options.

Parameters

$period
...$arguments

Return Value

bool

at line2316
bool isFollowedBy($period,...$arguments)

Return true if the given other period follows the current one (with no overlap).

For instance, [2019-07-29 -> 2019-07-31] is followed by [2019-08-01 -> 2019-08-12] Note than in this example, isFollowedBy() would be false if 2019-08-01 or 2019-07-31 was excluded by options.

Parameters

$period
...$arguments

Return Value

bool

at line2333
bool isConsecutiveWith($period,...$arguments)

Return true if the given period either follows or is followed by the current one.

Parameters

$period
...$arguments

Return Value

bool

See also

follows()
isFollowedBy()

at line2343
protectedvoid updateInternalState()

Update properties after removing built-in filters.

Return Value

void

at line2363
protectedarray createFilterTuple(array$parameters)

Create a filter tuple from raw parameters.

Will create an automatic filter callback for one of Carbon's is* methods.

Parameters

array $parameters

Return Value

array

at line2384
protectedbool isCarbonPredicateMethod(callable$callable)

Return whether given callable is a string pointing to one of Carbon's is* methods and should be automatically converted to a filter callback.

Parameters

callable $callable

Return Value

bool

at line2400
protectedbool|string filterRecurrences(Carbon$current,int$key)

Recurrences filter callback (limits number of recurrences).

Parameters

Carbon $current
int $key

Return Value

bool|string

at line2416
protectedbool|string filterEndDate(Carbon$current)

End date filter callback.

Parameters

Carbon $current

Return Value

bool|string

at line2434
protectedstring endIteration()

End iteration filter callback.

Return Value

string

at line2442
protected handleChangedParameters()

Handle change of the parameters.

at line2461
protectedbool|string validateCurrentDate()

Validate current date and stop iteration when necessary.

Returns true when current date is valid, false if it is not, or static::END_ITERATION when iteration should be stopped.

Return Value

bool|string

at line2476
protectedbool|string checkFilters()

Check whether current value and key pass all the filters.

Return Value

bool|string

at line2507
protectedCarbonInterface prepareForReturn(CarbonInterface$date)

Prepare given date to be returned to the external logic.

Parameters

CarbonInterface $date

Return Value

CarbonInterface

at line2525
protectedvoid incrementCurrentDateUntilValid()

Keep incrementing the current date until a valid date is found or the iteration is ended.

Return Value

void

Exceptions

RuntimeException

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

Call given macro.

Parameters

string $name
array $parameters

Return Value

mixed

at line2569
protectedCarbonInterface resolveCarbon(Carbon|CarbonPeriod|CarbonInterval|DateInterval|DatePeriod|DateTimeInterface|string|null$date =null)

Return the Carbon instance passed through, a now instance in the same timezone if null given or parse the input if string given.

at line2582
protectedCarbonPeriod resolveCarbonPeriod(mixed$period,mixed...$arguments)

Resolve passed arguments or DatePeriod to a CarbonPeriod object.

Parameters

mixed $period
mixed ...$arguments

Return Value

CarbonPeriod