Documentation

Time
in package

Various date and time utilities.

Table of Contents

Constants

COMPONENT_MAP  : mixed = ['year' => 'Y', 'month' => 'm', 'day' => 'd', '...
EMPTY_WEEK  : mixed = [1 => null, 2 => null, 3 => null, 4 => null, 5...
INTERVAL_UNITS  : mixed = ['y', 'm', 'd', 'h', 'i', 's', 'f']
MYSQL_DATE_FORMAT  : mixed = 'Y-m-d H:i:s'

Properties

$time_travel  : array{float, float}|null

Methods

between()  : Generator<string|int, DateTimeInterface>
Get a series of dates between these two dates.
createIntervalFromConfig()  : DateInterval
Create an interval from a config.
getDate()  : DateTimeImmutable
Get the the date in respect to time travel.
getIntervalConfig()  : array<string|int, mixed>
Create an interval config.
getIntervalString()  : string
Get the interval specification string.
getIntervalTotal()  : float
Get the total of an interval in the given unit.
getTimezoneOffset()  : string
Convert an IANA timezone into an offset string.
hasRelativeKeywords()  : bool
Check if a time string contains relative keywords.
localDateToUtc()  : string
Convert a local date string to a date string in UTC
localNow()  : string
Get the current datetime in the given timezone
modifyInterval()  : DateInterval
Modify an interval.
monthGrid()  : Generator<string|int, array<string|int, array<string|int, DateTimeInterface>>>
Get week aligned months.
monthOptions()  : array<string|int, string>
Get a list of month options for a dropdown as month_num => name
months()  : Generator<string|int, array<string|int, DateTimeInterface>>
Get groups of months.
now()  : DateTimeImmutable
Get the current date and selectively replace components.
parse()  : DateTimeInterface
Parse date strings and numbers into objects.
parseFloat()  : DateTimeImmutable
Convert a timestamp (with microseconds) into a date object.
parseInterval()  : DateInterval
Parse a time string into an interval.
parseTimeString()  : string|null
Validate + normalize a time string component.
pause()  : void
Pause or resume time travel.
periods()  : Generator<int, array<string|int, DateTimeInterface>>
Get a series of date periods between these two dates.
resume()  : void
Resume time travel.
setTimeTravel()  : void
Set time travel.
timeAgo()  : string
Returns a time in 'x minutes ago' format.
toDateTime()  : DateTime
Convert any date interface into a datetime.
toDateTimeImmutable()  : DateTimeImmutable
Convert any date interface into a immutable.
toTimeFloat()  : float
Get a unix timestamp as a float that includes microseconds.
toTimeMicroseconds()  : int
Get a unix timestamp in microseconds.
toTimeMilliseconds()  : int
Get a unix timestamp in milliseconds.
utcDateToLocal()  : string
Convert a UTC date string to a date string in the given timezone
utcDateToTime()  : int
Convert a date string to a timestamp in the given timezone
utcDateToTimeFloat()  : float
Convert a date string to a timestamp in the given timezone
utcTimeToDate()  : string
Convert a timestamp to a date string in the given timezone
utime()  : int
Timestamp as an integer in microseconds.
weekdays()  : array<string|int, string>
List of week day names (starting from Monday).
years()  : array<string|int, int>
List of years (starting from this year).

Constants

COMPONENT_MAP

public mixed COMPONENT_MAP = ['year' => 'Y', 'month' => 'm', 'day' => 'd', 'hour' => 'H', 'minute' => 'i', 'second' => 's']

EMPTY_WEEK

public mixed EMPTY_WEEK = [1 => null, 2 => null, 3 => null, 4 => null, 5 => null, 6 => null, 7 => null]

INTERVAL_UNITS

public mixed INTERVAL_UNITS = ['y', 'm', 'd', 'h', 'i', 's', 'f']

MYSQL_DATE_FORMAT

public mixed MYSQL_DATE_FORMAT = 'Y-m-d H:i:s'

Properties

$time_travel

protected static array{float, float}|null $time_travel = null

Methods

between()

Get a series of dates between these two dates.

public static between(DateTimeInterface $start, DateTimeInterface $end) : Generator<string|int, DateTimeInterface>
Parameters
$start : DateTimeInterface
$end : DateTimeInterface
Return values
Generator<string|int, DateTimeInterface>

createIntervalFromConfig()

Create an interval from a config.

public static createIntervalFromConfig(array<string|int, mixed> $config) : DateInterval

A config is a series of component keys:

  • y: years
  • m: months
  • d: days
  • h: hours
  • i: minutes
  • s: seconds
Parameters
$config : array<string|int, mixed>
Return values
DateInterval

getDate()

Get the the date in respect to time travel.

public static getDate([string $modifier = 'now' ]) : DateTimeImmutable
Parameters
$modifier : string = 'now'
Return values
DateTimeImmutable

getIntervalConfig()

Create an interval config.

public static getIntervalConfig(DateInterval $interval) : array<string|int, mixed>

This can be used to serialise an interval.

Parameters
$interval : DateInterval
Return values
array<string|int, mixed>

getIntervalString()

Get the interval specification string.

public static getIntervalString(DateInterval $interval[, int $subseconds = 0 ]) : string

This can be used to serialise intervals.

Parameters
$interval : DateInterval
$subseconds : int = 0

number of decimal places to include

Return values
string

getIntervalTotal()

Get the total of an interval in the given unit.

public static getIntervalTotal(DateInterval $interval[, string $unit = 'seconds' ]) : float

IMPORTANT: This is not a perfect conversion.

  • months are always 30 days
  • years are always 365 days
Parameters
$interval : DateInterval
$unit : string = 'seconds'
Return values
float

getTimezoneOffset()

Convert an IANA timezone into an offset string.

public static getTimezoneOffset(string|DateTimeZone $timezone[, DateTimeInterface|int|null $now = null ]) : string

The nature of offset strings means they're always relative to a specific time. If you can use timezone strings instead - you should.

Parameters
$timezone : string|DateTimeZone
$now : DateTimeInterface|int|null = null
Return values
string

hasRelativeKeywords()

Check if a time string contains relative keywords.

public static hasRelativeKeywords(string $time) : bool

For example: '+1 day', '+3 month', '+1 year'.

Parameters
$time : string
Return values
bool

localDateToUtc()

Convert a local date string to a date string in UTC

public static localDateToUtc(string $timezone, string $date[, string $format = 'Y-m-d H:i:s' ]) : string
Parameters
$timezone : string
$date : string
$format : string = 'Y-m-d H:i:s'
Return values
string —

The date string in the requested format

localNow()

Get the current datetime in the given timezone

public static localNow(string $timezone[, string $format = 'Y-m-d H:i:s' ]) : string
Parameters
$timezone : string
$format : string = 'Y-m-d H:i:s'
Return values
string —

The date string in the requested format

modifyInterval()

Modify an interval.

public static modifyInterval(DateInterval|array<string|int, mixed>|string ...$intervals) : DateInterval

As such, a contrived example:

$date = new DateTimeImmutable('2000-01-01');

$interval = $date->diff($date->modify('+2 days'));
$interval->format('%a days');
// => 2 days

$modified = modifyInterval($interval, '+2 days');
$modified->format('%a days');
// => 4 days
Parameters
$intervals : DateInterval|array<string|int, mixed>|string
Return values
DateInterval

monthGrid()

Get week aligned months.

public static monthGrid(int $year, int $from, int $to) : Generator<string|int, array<string|int, array<string|int, DateTimeInterface>>>

For example: April 2021

  Mo Tu We Th Fr Sa Su
   -  -  -  1  2  3  4
   5  6  7  8  9 10 11
  12 13 14 15 16 17 18
  19 20 21 22 23 24 25
  26 27 28 29 30  -  -

The output is a 3-dimension array.

[month][week][day] => DateTimeInterface

Parameters
$year : int
$from : int

1-indexed, inclusive

$to : int

1-indexed, inclusive

Return values
Generator<string|int, array<string|int, array<string|int, DateTimeInterface>>>

monthOptions()

Get a list of month options for a dropdown as month_num => name

public static monthOptions([int $length = 9 ][, string $format = 'F' ][, int $day = 1 ]) : array<string|int, string>
Parameters
$length : int = 9

substring length

$format : string = 'F'

date format AS per DateTime::format

$day : int = 1

day of the month, useful if using a day in the format

Return values
array<string|int, string>

months()

Get groups of months.

public static months(int $year, int $from, int $to) : Generator<string|int, array<string|int, DateTimeInterface>>

All inputs and outputs are 1-indexed.

For example: Time::months(2021, 1, 12) => January to December $months[1] => January $months[12] => December $months[2][1] => Feb 1st $months[2][28] => Feb 28th

Parameters
$year : int
$from : int

1-indexed, inclusive

$to : int

1-indexed, inclusive

Return values
Generator<string|int, array<string|int, DateTimeInterface>>

now()

Get the current date and selectively replace components.

public static now([array<string|int, mixed> $config = [] ]) : DateTimeImmutable

Example:

  // 'today' is 2021-02-03 14:30:10
  Time::now(['year' => 2000]);
  // => '2000-02-03 14:30:10'

  // Don't forget that `\date()` does this too:
  date('2000-m-d');
  // => 2000-02-03

  // But `new DateTime()` does not:
  new DateTime('2000-m-d');
  // => throws error

Config keys:

  • year
  • month
  • day
  • hour
  • minute
  • second
Parameters
$config : array<string|int, mixed> = []
Return values
DateTimeImmutable

parse()

Parse date strings and numbers into objects.

public static parse(mixed $value[, string|DateTimeZone|null $zone = null ]) : DateTimeInterface

Notable features:

  • pass-through date objects
  • parse integer as unix timestamps
  • support for microsecond timestamps (as float)
  • classic PHP date parsing
  • timezones
Parameters
$value : mixed
$zone : string|DateTimeZone|null = null
Tags
throws
InvalidArgumentException
Return values
DateTimeInterface

parseFloat()

Convert a timestamp (with microseconds) into a date object.

public static parseFloat(float $timestamp[, DateTimeZone|null $zone = null ]) : DateTimeImmutable
Parameters
$timestamp : float
$zone : DateTimeZone|null = null
Return values
DateTimeImmutable

parseInterval()

Parse a time string into an interval.

public static parseInterval(string $value) : DateInterval

This accepts:

  • shorthands like: 1y, 2d, 3h, 4m, 5s, 6ms, 7us (no support for months)
  • ISO 8601 periods like: P1Y2DT3H4M5S (with support for subseconds)
  • relative PHP date strings like: +1 day, -2 hours, 3 minutes, 4 seconds
Parameters
$value : string
Return values
DateInterval

parseTimeString()

Validate + normalize a time string component.

public static parseTimeString(mixed $time[, bool $big_endian = true ]) : string|null

A time-ish value is one of:

  • an integer (24-hour)
  • a float (24-hour with milliseconds)
  • starts with T (24-hour)
  • ends with am/pm (12-hour)

When parsing numbers (without a T prefix) the alignment can be either big endian or little endian.

  • Big endian (left align) means hours first: 1 => T01:00:00
  • Little endian (right align) means seconds first: 1 => T00:00:01

Values with a 'T' prefix are always big endian. Such as:

T101 => 'T10:10:00'

Parameters
$time : mixed
$big_endian : bool = true

left or right aligned number parsing

Return values
string|null —

T HH:MM:II.SSS

pause()

Pause or resume time travel.

public static pause([bool $pause = true ]) : void
Parameters
$pause : bool = true

periods()

Get a series of date periods between these two dates.

public static periods(DateTimeInterface $start, DateTimeInterface $end, string $period[, string|null $gap = null ]) : Generator<int, array<string|int, DateTimeInterface>>

For a 3 day period between 1st and 20th:

  • 0: [01-01-2000, 04-01-2000]
  • 1: [04-01-2000, 07-01-2000]
  • 2: [07-01-2000, 10-01-2000]
  • 3: [10-01-2000, 13-01-2000]
  • 4: [13-01-2000, 16-01-2000]
  • 5: [16-01-2000, 19-01-2000]
  • 6: [19-01-2000, 20-01-2000]

The last item will be truncated to the end of the period.

Provide the 'gap' argument insert a gap between the periods. For example, the same as above but with a 2 day gap:

  • 0: [01-01-2000, 03-01-2000]
  • 1: [05-02-2000, 08-01-2000]
  • 2: [10-02-2000, 13-01-2000]
  • 3: [15-02-2000, 18-01-2000]

The last item will be truncated if necessary but there's no guarantee that the last days will

Parameters
$start : DateTimeInterface
$end : DateTimeInterface
$period : string

A date modifier, like '+2 days'

$gap : string|null = null

A date modifier, a gap between each period

Return values
Generator<int, array<string|int, DateTimeInterface>> —

[start, end]

resume()

Resume time travel.

public static resume() : void

setTimeTravel()

Set time travel.

public static setTimeTravel(DateTimeImmutable|string|float|null $date) : void

Use null to clear time travel.

Parameters
$date : DateTimeImmutable|string|float|null

timeAgo()

Returns a time in 'x minutes ago' format.

public static timeAgo(int $timediff) : string

Very small times (0, 1 seconds) are considered 'Just now'. Times are represented in seconds, minutes, hours or days.

Parameters
$timediff : int

Amount of time that has passed, in seconds.

Return values
string

toDateTime()

Convert any date interface into a datetime.

public static toDateTime(DateTimeInterface $interface) : DateTime

use DateTime::createFromInterface() instead

Parameters
$interface : DateTimeInterface
Return values
DateTime

toDateTimeImmutable()

Convert any date interface into a immutable.

public static toDateTimeImmutable(DateTimeInterface $interface) : DateTimeImmutable

use DateTimeImmutable::createFromInterface() instead

Parameters
$interface : DateTimeInterface
Return values
DateTimeImmutable

toTimeFloat()

Get a unix timestamp as a float that includes microseconds.

public static toTimeFloat(DateTimeInterface $date) : float

This is more compatible with standard integer based timestamps than using the millisecond/microsecond helpers.

Parameters
$date : DateTimeInterface
Return values
float

toTimeMicroseconds()

Get a unix timestamp in microseconds.

public static toTimeMicroseconds(DateTimeInterface $date) : int
Parameters
$date : DateTimeInterface
Return values
int

toTimeMilliseconds()

Get a unix timestamp in milliseconds.

public static toTimeMilliseconds(DateTimeInterface $date) : int
Parameters
$date : DateTimeInterface
Return values
int

utcDateToLocal()

Convert a UTC date string to a date string in the given timezone

public static utcDateToLocal(string $timezone, string $date[, string $format = 'Y-m-d H:i:s' ]) : string
Parameters
$timezone : string
$date : string
$format : string = 'Y-m-d H:i:s'
Return values
string —

The date string in the requested format

utcDateToTime()

Convert a date string to a timestamp in the given timezone

public static utcDateToTime(string $timezone, string $date) : int
Parameters
$timezone : string
$date : string
Return values
int —

The timestamp

utcDateToTimeFloat()

Convert a date string to a timestamp in the given timezone

public static utcDateToTimeFloat(string $timezone, string $date) : float
Parameters
$timezone : string
$date : string
Return values
float —

The timestamp with microseconds

utcTimeToDate()

Convert a timestamp to a date string in the given timezone

public static utcTimeToDate(string $timezone, float $timestamp[, string $format = 'Y-m-d H:i:s' ]) : string
Parameters
$timezone : string
$timestamp : float
$format : string = 'Y-m-d H:i:s'
Tags
throws
InvalidArgumentException
Return values
string —

The date string in the requested format

utime()

Timestamp as an integer in microseconds.

public static utime([bool $hrtime = true ]) : int

Note, if using hrtime the timestamp is not a unix epoch.

Parameters
$hrtime : bool = true

Use high-resolution (default)

Return values
int —

microseconds

weekdays()

List of week day names (starting from Monday).

public static weekdays([int $length = 0 ]) : array<string|int, string>
Parameters
$length : int = 0

substring length

Return values
array<string|int, string>

years()

List of years (starting from this year).

public static years([int $length = 5 ][, int|null $year = null ]) : array<string|int, int>
Parameters
$length : int = 5

number of years to include

$year : int|null = null

start year

Return values
array<string|int, int>
On this page

Search results