DateTimeHelper

Type

Class

Namespace

craft\helpers

Inherits

craft\helpers\DateTimeHelper

Since

3.0.0

Class DateTimeHelper

View source

Public Methods

Method	Description
currentTimeStamp()	Returns the current Unix time stamp (factoring in whether time is paused).
currentUTCDateTime()	Returns a DateTime object set to the current time (factoring in whether time is paused), in the UTC time zone.
firstWeekDay()	Returns the index of the first day of the week (0-6), according to the user’s preferences.
humanDuration()	Returns a human-friendly duration string for the given date interval or number of seconds.
humanDurationFromInterval()	Returns the interval in a human-friendly string.
intervalToSeconds()	Returns the number of seconds that a given DateInterval object spans.
isInThePast()	Returns true if the specified date was in the past, otherwise false.
isIso8601()	Determines whether the given value is an ISO-8601-formatted date, as formatted by either DateTime::ATOM or DateTime::ISO8601 (with or without the colon between the hours and minutes of the timezone).
isThisMonth()	Returns true if given date is in this month
isThisWeek()	Returns true if given date is in this week
isThisYear()	Returns true if given date is in this year
isToday()	Returns true if given date is today.
isValidIntervalString()	Returns true if interval string is a valid interval.
isValidTimeStamp()
isWithinLast()	Returns true if specified datetime was within the interval specified, else false.
isYesterday()	Returns true if given date was yesterday
lastMonth()	Returns a DateTime object set to midnight of the first day of last month (factoring in whether time is paused).
lastWeek()	Returns a DateTime object set to midnight of the first day of last week, according to the user’s preferences (factoring in whether time is paused).
lastYear()	Returns a DateTime object set to midnight of the first day of last year (factoring in whether time is paused).
nextMonth()	Returns a DateTime object set to midnight of the first day of next month (factoring in whether time is paused).
nextWeek()	Returns a DateTime object set to midnight of the first day of next week, according to the user’s preferences (factoring in whether time is paused).
nextYear()	Returns a DateTime object set to midnight of the first day of next year (factoring in whether time is paused).
normalizeTimeZone()	Normalizes a timezone string to a PHP timezone identifier.
now()	Returns a DateTime object set to the current time (factoring in whether time is paused).
pause()	Pauses time for any subsequent calls to other DateTimeHelper methods, until resume() is called.
relativeTimeStatement()	Returns a relative time statement based on the given number and unit.
relativeTimeToSeconds()	Converts a relative time (number and unit) to seconds.
resume()	Resumes time, if it was paused via pause().
secondsToHumanTimeDuration()
secondsToInterval()	Creates a DateInterval object based on a given number of seconds.
thisMonth()	Returns a DateTime object set to midnight of the first day of this month (factoring in whether time is paused).
thisWeek()	Returns a DateTime object set to midnight of the first day of this week, according to the user’s preferences (factoring in whether time is paused).
thisYear()	Returns a DateTime object set to midnight of the first day of this year (factoring in whether time is paused).
timeZoneAbbreviation()	Returns the timezone abbreviation for a given timezone name.
timeZoneOffset()	Returns a given timezone’s offset from UTC (e.g. '+10:00' or '-06:00').
toDateInterval()	Converts a value into a DateInterval object.
toDateTime()	Converts a value into a DateTime object.
toIso8601()	Converts a date to an ISO-8601 string.
today()	Returns a DateTime object set to midnight of the current day (factoring in whether time is paused).
tomorrow()	Returns a DateTime object set to midnight of the following day (factoring in whether time is paused).
yesterday()	Returns a DateTime object set to midnight of the previous day (factoring in whether time is paused).

currentTimeStamp()

Returns the current Unix time stamp (factoring in whether time is paused).

View source

Returns

integer

currentUTCDateTime()

Returns a DateTime object set to the current time (factoring in whether time is paused), in the UTC time zone.

View source

Returns

DateTime

firstWeekDay()

Since

4.3.0

Returns the index of the first day of the week (0-6), according to the user’s preferences.

View source

Returns

integer

humanDuration()

Since

4.2.0

Returns a human-friendly duration string for the given date interval or number of seconds.

View source

Arguments

• $dateInterval (mixed) – The value, represented as either a DateInterval object, an interval duration string, or a number of seconds.
• $showSeconds (boolean, null) – Whether the duration string should include the number of seconds

Returns

string

humanDurationFromInterval()

DEPRECATED

Deprecated in 4.2.0. humanDuration() should be used instead.

Returns the interval in a human-friendly string.

View source

Arguments

• $dateInterval (DateInterval)
• $showSeconds (boolean)

Returns

string

intervalToSeconds()

Returns the number of seconds that a given DateInterval object spans.

View source

Arguments

• $dateInterval (DateInterval)

Returns

integer

isInThePast()

Returns true if the specified date was in the past, otherwise false.

View source

Arguments

• $date (mixed) – The timestamp to check

Returns

boolean – True if the specified date was in the past, false otherwise.

isIso8601()

Determines whether the given value is an ISO-8601-formatted date, as formatted by either DateTime::ATOM or DateTime::ISO8601 (with or without the colon between the hours and minutes of the timezone).

View source

Arguments

• $value (mixed) – The timestamp to check

Returns

boolean – Whether the value is an ISO-8601 date string

isThisMonth()

Returns true if given date is in this month

View source

Arguments

• $date (mixed) – The timestamp to check

Returns

boolean – True if date is in this month, false otherwise.

isThisWeek()

Returns true if given date is in this week

View source

Arguments

• $date (mixed) – The timestamp to check

Returns

boolean – True if date is in this week, false otherwise.

isThisYear()

Returns true if given date is in this year

View source

Arguments

• $date (mixed) – The timestamp to check

Returns

boolean – True if date is in this year, false otherwise.

isToday()

Returns true if given date is today.

View source

Arguments

• $date (mixed) – The timestamp to check

Returns

boolean – True if date is today, false otherwise.

isValidIntervalString()

Returns true if interval string is a valid interval.

View source

Arguments

• $intervalString (string)

Returns

boolean

isValidTimeStamp()

View source

Arguments

• $timestamp (mixed)

Returns

boolean

isWithinLast()

Returns true if specified datetime was within the interval specified, else false.

View source

Arguments

• $date (mixed) – The timestamp to check
• $timeInterval (mixed) – The numeric value with space then time type. Example of valid types: '6 hours', '2 days', '1 minute'.

Returns

boolean – Whether the $dateString was within the specified $timeInterval.

Throws

• yii\base\InvalidArgumentException

isYesterday()

Returns true if given date was yesterday

View source

Arguments

• $date (mixed) – The timestamp to check

Returns

boolean – True if date was yesterday, false otherwise.

lastMonth()

Since

4.3.0

Returns a DateTime object set to midnight of the first day of last month (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

lastWeek()

Since

4.3.0

Returns a DateTime object set to midnight of the first day of last week, according to the user’s preferences (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

lastYear()

Since

4.3.0

Returns a DateTime object set to midnight of the first day of last year (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

nextMonth()

Since

4.3.0

Returns a DateTime object set to midnight of the first day of next month (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

nextWeek()

Since

4.3.0

Returns a DateTime object set to midnight of the first day of next week, according to the user’s preferences (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

nextYear()

Since

4.3.0

Returns a DateTime object set to midnight of the first day of next year (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

normalizeTimeZone()

Normalizes a timezone string to a PHP timezone identifier.

Supports the following formats:

• Time zone abbreviation (EST, MDT)
• Difference to Greenwich time (GMT) in hours, with/without a colon between the hours and minutes (+0200, -0200, +02:00, -02:00)
• A PHP timezone identifier (UTC, GMT, Atlantic/Azores)

View source

Arguments

• $timeZone (string) – The timezone to be normalized

Returns

string, false – The PHP timezone identifier, or false if it could not be determined

now()

Since

4.1.0

Returns a DateTime object set to the current time (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

pause()

Since

4.1.0

Pauses time for any subsequent calls to other DateTimeHelper methods, until resume() is called.

If this method is called multiple times, resume() will need to be called an equal number of times before time is actually resumed.

View source

Arguments

• $now (DateTime, null) – A DateTime object that should represent the current time for the duration of the pause

relativeTimeStatement()

Since

4.10.0

Returns a relative time statement based on the given number and unit.

View source

Arguments

• $number (integer)
• $unit (string)

Returns

string

relativeTimeToSeconds()

Since

4.10.0

Converts a relative time (number and unit) to seconds.

View source

Arguments

• $number (integer)
• $unit (string)

Returns

integer

resume()

Since

4.1.0

Resumes time, if it was paused via pause().

View source

secondsToHumanTimeDuration()

DEPRECATED

Deprecated in 4.2.0. humanDuration() should be used instead.

View source

Arguments

• $seconds (integer) – The number of seconds
• $showSeconds (boolean) – Whether to output seconds or not

Returns

string

secondsToInterval()

DEPRECATED

Deprecated in 4.2.1. toDateInterval() should be used instead.

Creates a DateInterval object based on a given number of seconds.

View source

Arguments

• $seconds (integer)

Returns

DateInterval

thisMonth()

Since

4.3.0

Returns a DateTime object set to midnight of the first day of this month (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

thisWeek()

Since

4.3.0

Returns a DateTime object set to midnight of the first day of this week, according to the user’s preferences (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

thisYear()

Since

4.3.0

Returns a DateTime object set to midnight of the first day of this year (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

timeZoneAbbreviation()

DEPRECATED

Deprecated in 4.3.7

Returns the timezone abbreviation for a given timezone name.

View source

Arguments

• $timeZone (string)

Returns

string

timeZoneOffset()

DEPRECATED

Deprecated in 4.3.7

Returns a given timezone’s offset from UTC (e.g. '+10:00' or '-06:00').

View source

Arguments

• $timeZone (string)

Returns

string

toDateInterval()

Since

4.2.1

Converts a value into a DateInterval object.

View source

Arguments

• $value (mixed) – The value, represented as either a DateInterval object, an interval duration string, or a number of seconds.

Returns

DateInterval, false

Throws

• yii\base\InvalidArgumentException

toDateTime()

Converts a value into a DateTime object.

$value can be in the following formats:

• All W3C date and time formats (http://www.w3.org/TR/NOTE-datetime)
• MySQL DATE and DATETIME formats (http://dev.mysql.com/doc/refman/5.1/en/datetime.html)
• Relaxed versions of W3C and MySQL formats (single-digit months, days, and hours)
• Unix timestamps
• now/today/tomorrow/yesterday (midnight of the specified relative date)
• An array with at least one of these keys defined: datetime, date, or time. Supported keys include:
  • date – A date string in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.MU formats or the current locale’s short date format.
  • time – A time string in HH:MM or HH:MM:SS (24-hour) format or the current locale’s short time format.
  • datetime – A timestamp in any of the non-array formats supported by this method
  • locale – The locale ID that the date and time were formatted in. Defaults to the app’s current formatting locale.
  • timezone – A valid PHP timezone. If set, this will override the assumed timezone per $assumeSystemTimeZone.

View source

Arguments

• $value (string, integer, array, DateTimeInterface, null) – The value that should be converted to a DateTime object.
• $assumeSystemTimeZone (boolean) – Whether it should be assumed that the value was set in the system timezone if the timezone was not specified. If this is false, UTC will be assumed.
• $setToSystemTimeZone (boolean) – Whether to set the resulting DateTime object to the system timezone.

Returns

DateTime, false – The DateTime object, or false if $object could not be converted to one

Throws

• Exception

toIso8601()

Converts a date to an ISO-8601 string.

View source

Arguments

• $date (mixed) – The date, in any format that toDateTime() supports.

Returns

string, false – The date formatted as an ISO-8601 string, or false if $date was not a valid date

today()

Since

4.3.0

Returns a DateTime object set to midnight of the current day (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

tomorrow()

Since

4.3.0

Returns a DateTime object set to midnight of the following day (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

yesterday()

Since

4.3.0

Returns a DateTime object set to midnight of the previous day (factoring in whether time is paused).

View source

Arguments

• $timeZone (DateTimeZone, null) – The time zone to return the DateTime object in. (Defaults to the system time zone.)

Returns

DateTime

Constants

Constant	Description
RELATIVE_TIME_UNITS
SECONDS_DAY
SECONDS_HOUR
SECONDS_MINUTE
SECONDS_MONTH
SECONDS_YEAR