Documentation

CarbonInterval extends DateInterval
in package

A simple API extension for DateInterval.

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

Table of Contents

PERIOD_DAYS  = 'D'
PERIOD_HOURS  = 'H'
PERIOD_MINUTES  = 'M'
PERIOD_MONTHS  = 'M'
PERIOD_PREFIX  = 'P'
Interval spec period designators
PERIOD_SECONDS  = 'S'
PERIOD_TIME_PREFIX  = 'T'
PERIOD_YEARS  = 'Y'
PHP_DAYS_FALSE  = -99999
Before PHP 5.4.20/5.5.4 instead of FALSE days will be set to -99999 when the interval instance was created by DateTime::diff().
$daysExcludeWeeks  : int
$dayz  : int
$dayzExcludeWeeks  : int
$hours  : int
$minutes  : int
$months  : int
$seconds  : int
$totalDays  : float
$totalDayz  : float
$totalHours  : float
$totalMinutes  : float
$totalMonths  : float
$totalSeconds  : float
$totalWeeks  : float
$totalYears  : float
$weeks  : int
$years  : int
$cascadeFactors  : array<string|int, mixed>|null
$macros  : array<string|int, mixed>
The registered macros.
$translator  : TranslatorInterface
A translator to ... er ... translate stuff
$flipCascadeFactors  : array<string|int, mixed>|null
__call()  : static
Allow fluent calls on the setters... CarbonInterval::years(3)->months(5)->day().
__callStatic()  : static
Provide static helpers to create instances. Allows CarbonInterval::years(3).
__construct()  : mixed
Create a new CarbonInterval instance.
__get()  : int|float
Get a part of the CarbonInterval object.
__set()  : mixed
Set a part of the CarbonInterval object.
__toString()  : string
Format the instance as a string using the forHumans() function.
add()  : static
Add the passed interval to the current instance.
cascade()  : $this
Convert overflowed values into bigger units.
compare()  : int
Comparing with passed interval.
compareDateIntervals()  : int
Comparing 2 date intervals.
copy()  : static
Get a copy of the instance.
create()  : static
Create a new CarbonInterval instance from specific values.
day()  :
day()  :
days()  :
days()  :
dayz()  :
dayz()  :
forHumans()  : string
Get the current interval in a human readable format in the current locale.
fromString()  : static
Creates a CarbonInterval from string.
getCascadeFactors()  : array<string|int, mixed>
Mapping of units and factors for cascading.
getDateIntervalSpec()  : string
Get the interval_spec string of a date interval.
getDaysPerWeek()  : int
Returns current config for days per week.
getFactor()  : int|null
Returns the factor for a given source-to-target couple.
getHoursPerDay()  : int
Returns current config for hours per day.
getLocale()  : string
Get the current translator locale.
getMinutesPerHours()  : int
Returns current config for minutes per hour.
getSecondsPerMinutes()  : int
Returns current config for seconds per minute.
getTranslator()  : TranslatorInterface
Get the translator instance in use.
hasMacro()  : bool
Check if macro is registered.
hour()  :
hour()  :
hours()  :
hours()  :
instance()  : static
Create a CarbonInterval instance from a DateInterval one. Can not instance DateInterval objects created from DateTime::diff() as you can't externally set the $days field.
invert()  : $this
Invert the interval.
macro()  : void
Register a custom macro.
make()  : static|null
Make a CarbonInterval instance from given variable if possible.
minute()  :
minute()  :
minutes()  :
minutes()  :
mixin()  : void
Register macros from a mixin object.
month()  :
month()  :
months()  :
months()  :
resetMacros()  : mixed
Remove all macros.
second()  :
second()  :
seconds()  :
seconds()  :
setCascadeFactors()  : mixed
setLocale()  : mixed
Set the current translator locale.
setTranslator()  : mixed
Set the translator instance to use.
spec()  : string
Get the interval_spec string.
times()  : $this
Multiply current instance given number of times
toPeriod()  : CarbonPeriod
Convert the interval to a CarbonPeriod.
total()  : float
Get amount of given unit equivalent to the interval.
week()  :
week()  :
weeks()  :
weeks()  :
weeksAndDays()  : static
Allow setting of weeks and days to be cumulative.
year()  :
year()  :
years()  :
years()  :
callMacro()  : mixed
Call given macro.
translator()  : TranslatorInterface
Initialize the translator instance if necessary.
getFlipCascadeFactors()  : mixed
standardizeUnit()  : mixed
wasCreatedFromDiff()  : bool
Determine if the interval was created via DateTime:diff() or not.

Constants

PERIOD_PREFIX

Interval spec period designators

public mixed PERIOD_PREFIX = 'P'

PHP_DAYS_FALSE

Before PHP 5.4.20/5.5.4 instead of FALSE days will be set to -99999 when the interval instance was created by DateTime::diff().

public mixed PHP_DAYS_FALSE = -99999

Properties

$daysExcludeWeeks read-only

public int $daysExcludeWeeks

alias of dayzExcludeWeeks

$dayz

public int $dayz

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

$dayzExcludeWeeks read-only

public int $dayzExcludeWeeks

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

$minutes

public int $minutes

Total minutes of the current interval.

$seconds

public int $seconds

Total seconds of the current interval.

$totalDays read-only

public float $totalDays

Number of days equivalent to the interval.

$totalDayz read-only

public float $totalDayz

Alias for totalDays.

$totalHours read-only

public float $totalHours

Number of hours equivalent to the interval.

$totalMinutes read-only

public float $totalMinutes

Number of minutes equivalent to the interval.

$totalMonths read-only

public float $totalMonths

Number of months equivalent to the interval.

$totalSeconds read-only

public float $totalSeconds

Number of seconds equivalent to the interval.

$totalWeeks read-only

public float $totalWeeks

Number of weeks equivalent to the interval.

$totalYears read-only

public float $totalYears

Number of years equivalent to the interval.

$weeks

public int $weeks

Total weeks of the current interval calculated from the days.

$cascadeFactors

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

$macros

The registered macros.

protected static array<string|int, mixed> $macros = array()

$flipCascadeFactors

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

Methods

__call()

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

public __call(string $name, array<string|int, mixed> $args) : static

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

Parameters
$name : string
$args : array<string|int, mixed>
Return values
static —

__callStatic()

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

public static __callStatic(string $name, array<string|int, mixed> $args) : static

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

Parameters
$name : string
$args : array<string|int, mixed>
Return values
static —

__construct()

Create a new CarbonInterval instance.

public __construct([int $years = 1 ][, int $months = null ][, int $weeks = null ][, int $days = null ][, int $hours = null ][, int $minutes = null ][, int $seconds = null ]) : mixed
Parameters
$years : int = 1
$months : int = null
$weeks : int = null
$days : int = null
$hours : int = null
$minutes : int = null
$seconds : int = null
Return values
mixed —

__get()

Get a part of the CarbonInterval object.

public __get(string $name) : int|float
Parameters
$name : string
Tags
throws
InvalidArgumentException
Return values
int|float —

__set()

Set a part of the CarbonInterval object.

public __set(string $name, int $val) : mixed
Parameters
$name : string
$val : int
Tags
throws
InvalidArgumentException
Return values
mixed —

__toString()

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

public __toString() : string
Return values
string —

add()

Add the passed interval to the current instance.

public add(DateInterval $interval) : static
Parameters
$interval : DateInterval
Return values
static —

cascade()

Convert overflowed values into bigger units.

public cascade() : $this
Return values
$this —

compare()

Comparing with passed interval.

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

compareDateIntervals()

Comparing 2 date intervals.

public static compareDateIntervals(DateInterval $a, DateInterval $b) : int
Parameters
$a : DateInterval
$b : DateInterval
Return values
int —

copy()

Get a copy of the instance.

public copy() : static
Return values
static —

create()

Create a new CarbonInterval instance from specific values.

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

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

Parameters
$years : int = 1
$months : int = null
$weeks : int = null
$days : int = null
$hours : int = null
$minutes : int = null
$seconds : int = null
Return values
static —

day()

public static day(mixed $days) :

Alias for days()

Parameters
$days : mixed
Return values
—

day()

public day(mixed $days) :

Alias for days().

Parameters
$days : mixed
Return values
—

days()

public days(mixed $days) :

Set the days portion of the current interval.

Parameters
$days : mixed
Return values
—

days()

public static days(mixed $days) :

Create instance specifying a number of days.

Parameters
$days : mixed
Return values
—

dayz()

public static dayz(mixed $days) :

Alias for days()

Parameters
$days : mixed
Return values
—

dayz()

public dayz(mixed $days) :

Alias for days().

Parameters
$days : mixed
Return values
—

forHumans()

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

public forHumans([bool $short = false ]) : string
Parameters
$short : bool = false

(false by default), returns short units if true

Return values
string —

fromString()

Creates a CarbonInterval from string.

public static fromString(string $intervalDefinition) : static

Format:

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

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

Special cases:

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

getCascadeFactors()

Mapping of units and factors for cascading.

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

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

Return values
array<string|int, mixed> —

getDateIntervalSpec()

Get the interval_spec string of a date interval.

public static getDateIntervalSpec(DateInterval $interval) : string
Parameters
$interval : DateInterval
Return values
string —

getDaysPerWeek()

Returns current config for days per week.

public static getDaysPerWeek() : int
Return values
int —

getFactor()

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

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

getHoursPerDay()

Returns current config for hours per day.

public static getHoursPerDay() : int
Return values
int —

getLocale()

Get the current translator locale.

public static getLocale() : string
Return values
string —

getMinutesPerHours()

Returns current config for minutes per hour.

public static getMinutesPerHours() : int
Return values
int —

getSecondsPerMinutes()

Returns current config for seconds per minute.

public static getSecondsPerMinutes() : int
Return values
int —

hasMacro()

Check if macro is registered.

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

hour()

public static hour(mixed $hours) :

Alias for hours()

Parameters
$hours : mixed
Return values
—

hour()

public hour(mixed $hours) :

Alias for hours().

Parameters
$hours : mixed
Return values
—

hours()

public static hours(mixed $hours) :

Create instance specifying a number of hours.

Parameters
$hours : mixed
Return values
—

hours()

public hours(mixed $hours) :

Set the hours portion of the current interval.

Parameters
$hours : mixed
Return values
—

instance()

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

public static instance(DateInterval $di[, bool $trimMicroseconds = true ]) : static

Pass false as second argument to get a microseconds-precise interval. Else microseconds in the original interval will not be kept.

Parameters
$di : DateInterval
$trimMicroseconds : bool = true

(true by default)

Return values
static —

invert()

Invert the interval.

public invert() : $this
Return values
$this —

macro()

Register a custom macro.

public static macro(string $name, object|callable $macro) : void
Parameters
$name : string
$macro : object|callable
Return values
void —

make()

Make a CarbonInterval instance from given variable if possible.

public static make(mixed $var) : static|null

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

Parameters
$var : mixed
Return values
static|null —

minute()

public minute(mixed $minutes) :

Alias for minutes().

Parameters
$minutes : mixed
Return values
—

minute()

public static minute(mixed $minutes) :

Alias for minutes()

Parameters
$minutes : mixed
Return values
—

minutes()

public minutes(mixed $minutes) :

Set the minutes portion of the current interval.

Parameters
$minutes : mixed
Return values
—

minutes()

public static minutes(mixed $minutes) :

Create instance specifying a number of minutes.

Parameters
$minutes : mixed
Return values
—

mixin()

Register macros from a mixin object.

public static mixin(object $mixin) : void
Parameters
$mixin : object
Tags
throws
ReflectionException
Return values
void —

month()

public month(mixed $months) :

Alias for months().

Parameters
$months : mixed
Return values
—

month()

public static month(mixed $months) :

Alias for months()

Parameters
$months : mixed
Return values
—

months()

public months(mixed $months) :

Set the months portion of the current interval.

Parameters
$months : mixed
Return values
—

months()

public static months(mixed $months) :

Create instance specifying a number of months.

Parameters
$months : mixed
Return values
—

resetMacros()

Remove all macros.

public static resetMacros() : mixed
Return values
mixed —

second()

public static second(mixed $seconds) :

Alias for seconds()

Parameters
$seconds : mixed
Return values
—

second()

public second(mixed $seconds) :

Alias for seconds().

Parameters
$seconds : mixed
Return values
—

seconds()

public seconds(mixed $seconds) :

Set the seconds portion of the current interval.

Parameters
$seconds : mixed
Return values
—

seconds()

public static seconds(mixed $seconds) :

Create instance specifying a number of seconds.

Parameters
$seconds : mixed
Return values
—

setCascadeFactors()

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

setLocale()

Set the current translator locale.

public static setLocale(string $locale) : mixed
Parameters
$locale : string
Return values
mixed —

spec()

Get the interval_spec string.

public spec() : string
Return values
string —

times()

Multiply current instance given number of times

public times(float $factor) : $this
Parameters
$factor : float
Return values
$this —

total()

Get amount of given unit equivalent to the interval.

public total(string $unit) : float
Parameters
$unit : string
Tags
throws
InvalidArgumentException
Return values
float —

week()

public week(mixed $weeks) :

Alias for weeks().

Parameters
$weeks : mixed
Return values
—

week()

public static week(mixed $weeks) :

Alias for weeks()

Parameters
$weeks : mixed
Return values
—

weeks()

public weeks(mixed $weeks) :

Set the weeks portion of the current interval. Will overwrite dayz value.

Parameters
$weeks : mixed
Return values
—

weeks()

public static weeks(mixed $weeks) :

Create instance specifying a number of weeks.

Parameters
$weeks : mixed
Return values
—

weeksAndDays()

Allow setting of weeks and days to be cumulative.

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

Number of weeks to set

$days : int

Number of days to set

Return values
static —

year()

public static year(mixed $years) :

Alias for years()

Parameters
$years : mixed
Return values
—

year()

public year(mixed $years) :

Alias for years().

Parameters
$years : mixed
Return values
—

years()

public years(mixed $years) :

Set the years portion of the current interval.

Parameters
$years : mixed
Return values
—

years()

public static years(mixed $years) :

Create instance specifying a number of years.

Parameters
$years : mixed
Return values
—

callMacro()

Call given macro.

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

getFlipCascadeFactors()

private static getFlipCascadeFactors() : mixed
Return values
mixed —

standardizeUnit()

private static standardizeUnit(mixed $unit) : mixed
Parameters
$unit : mixed
Return values
mixed —

wasCreatedFromDiff()

Determine if the interval was created via DateTime:diff() or not.

private static wasCreatedFromDiff(DateInterval $interval) : bool
Parameters
$interval : DateInterval
Return values
bool —

Search results