DateTimeHelper
- Type
- Class
- Namespace
- craft\helpers
- Inherits
- craft\helpers\DateTimeHelper
- Since
- 3.0.0
Class DateTimeHelper
View source (opens new window)
# Public Methods
Method | Description |
---|---|
currentTimeStamp() | Returns the current Unix time stamp (factoring in whether time is paused). |
currentUTCDateTime() | Returns a DateTime (opens new window) 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 (opens new window) or DateTime::ISO8601 (opens new window) (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 (opens new window) object set to midnight of the first day of last month (factoring in whether time is paused). |
lastWeek() | Returns a DateTime (opens new window) 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 (opens new window) object set to midnight of the first day of last year (factoring in whether time is paused). |
nextMonth() | Returns a DateTime (opens new window) object set to midnight of the first day of next month (factoring in whether time is paused). |
nextWeek() | Returns a DateTime (opens new window) 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 (opens new window) 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 (opens new window) 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. |
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 (opens new window) object set to midnight of the first day of this month (factoring in whether time is paused). |
thisWeek() | Returns a DateTime (opens new window) 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 (opens new window) 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 (opens new window) object set to midnight of the current day (factoring in whether time is paused). |
tomorrow() | Returns a DateTime (opens new window) object set to midnight of the following day (factoring in whether time is paused). |
yesterday() | Returns a DateTime (opens new window) 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 (opens new window)
Returns
# currentUTCDateTime()
Returns a DateTime (opens new window) object set to the current time (factoring in whether time is paused), in the UTC time zone.
View source (opens new window)
Returns
# 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 (opens new window)
Returns
# humanDuration()
- Since
- 4.2.0
Returns a human-friendly duration string for the given date interval or number of seconds.
View source (opens new window)
Arguments
$dateInterval
(mixed
) – The value, represented as either a DateInterval (opens new window) object, an interval duration string, or a number of seconds.$showSeconds
(boolean (opens new window), null (opens new window)) – Whether the duration string should include the number of seconds
Returns
# humanDurationFromInterval()
DEPRECATED
Deprecated in 4.2.0. humanDuration() should be used instead.
Returns the interval in a human-friendly string.
View source (opens new window)
Arguments
$dateInterval
(DateInterval (opens new window))$showSeconds
(boolean (opens new window))
Returns
# intervalToSeconds()
Returns the number of seconds that a given DateInterval object spans.
View source (opens new window)
Arguments
$dateInterval
(DateInterval (opens new window))
Returns
# isInThePast()
Returns true if the specified date was in the past, otherwise false.
View source (opens new window)
Arguments
$date
(mixed
) – The timestamp to check
Returns
boolean (opens new window) – 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 (opens new window) or DateTime::ISO8601 (opens new window) (with or without the colon between the hours and minutes of the timezone).
View source (opens new window)
Arguments
$value
(mixed
) – The timestamp to check
Returns
boolean (opens new window) – Whether the value is an ISO-8601 date string
# isThisMonth()
Returns true if given date is in this month
View source (opens new window)
Arguments
$date
(mixed
) – The timestamp to check
Returns
boolean (opens new window) – True if date is in this month, false otherwise.
# isThisWeek()
Returns true if given date is in this week
View source (opens new window)
Arguments
$date
(mixed
) – The timestamp to check
Returns
boolean (opens new window) – True if date is in this week, false otherwise.
# isThisYear()
Returns true if given date is in this year
View source (opens new window)
Arguments
$date
(mixed
) – The timestamp to check
Returns
boolean (opens new window) – True if date is in this year, false otherwise.
# isToday()
Returns true if given date is today.
View source (opens new window)
Arguments
$date
(mixed
) – The timestamp to check
Returns
boolean (opens new window) – True if date is today, false otherwise.
# isValidIntervalString()
Returns true if interval string is a valid interval.
View source (opens new window)
Arguments
$intervalString
(string (opens new window))
Returns
# isValidTimeStamp()
View source (opens new window)
Arguments
$timestamp
(mixed
)
Returns
# isWithinLast()
Returns true if specified datetime was within the interval specified, else false.
View source (opens new window)
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 (opens new window) – Whether the $dateString was within the specified $timeInterval.
Throws
# isYesterday()
Returns true if given date was yesterday
View source (opens new window)
Arguments
$date
(mixed
) – The timestamp to check
Returns
boolean (opens new window) – True if date was yesterday, false otherwise.
# lastMonth()
- Since
- 4.3.0
Returns a DateTime (opens new window) object set to midnight of the first day of last month (factoring in whether time is paused).
View source (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# lastWeek()
- Since
- 4.3.0
Returns a DateTime (opens new window) 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 (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# lastYear()
- Since
- 4.3.0
Returns a DateTime (opens new window) object set to midnight of the first day of last year (factoring in whether time is paused).
View source (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# nextMonth()
- Since
- 4.3.0
Returns a DateTime (opens new window) object set to midnight of the first day of next month (factoring in whether time is paused).
View source (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# nextWeek()
- Since
- 4.3.0
Returns a DateTime (opens new window) 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 (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# nextYear()
- Since
- 4.3.0
Returns a DateTime (opens new window) object set to midnight of the first day of next year (factoring in whether time is paused).
View source (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# 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 (opens new window)
Arguments
$timeZone
(string (opens new window)) – The timezone to be normalized
Returns
string (opens new window), false (opens new window) – The PHP timezone identifier, or false
if it could not be determined
# now()
- Since
- 4.1.0
Returns a DateTime (opens new window) object set to the current time (factoring in whether time is paused).
View source (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# 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 (opens new window)
Arguments
$now
(DateTime (opens new window), null (opens new window)) – ADateTime
object that should represent the current time for the duration of the pause
# resume()
- Since
- 4.1.0
Resumes time, if it was paused via pause().
View source (opens new window)
# secondsToHumanTimeDuration()
DEPRECATED
Deprecated in 4.2.0. humanDuration() should be used instead.
View source (opens new window)
Arguments
$seconds
(integer (opens new window)) – The number of seconds$showSeconds
(boolean (opens new window)) – Whether to output seconds or not
Returns
# 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 (opens new window)
Arguments
$seconds
(integer (opens new window))
Returns
DateInterval (opens new window)
# thisMonth()
- Since
- 4.3.0
Returns a DateTime (opens new window) object set to midnight of the first day of this month (factoring in whether time is paused).
View source (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# thisWeek()
- Since
- 4.3.0
Returns a DateTime (opens new window) 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 (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# thisYear()
- Since
- 4.3.0
Returns a DateTime (opens new window) object set to midnight of the first day of this year (factoring in whether time is paused).
View source (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# timeZoneAbbreviation()
DEPRECATED
Deprecated in 4.3.7
Returns the timezone abbreviation for a given timezone name.
View source (opens new window)
Arguments
$timeZone
(string (opens new window))
Returns
# timeZoneOffset()
DEPRECATED
Deprecated in 4.3.7
Returns a given timezone’s offset from UTC (e.g. '+10:00' or '-06:00').
View source (opens new window)
Arguments
$timeZone
(string (opens new window))
Returns
# toDateInterval()
- Since
- 4.2.1
Converts a value into a DateInterval object.
View source (opens new window)
Arguments
$value
(mixed
) – The value, represented as either a DateInterval (opens new window) object, an interval duration string, or a number of seconds.
Returns
DateInterval (opens new window), false (opens new window)
Throws
# 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
, ortime
. Supported keys include:date
– A date string inYYYY-MM-DD
orYYYY-MM-DD HH:MM:SS.MU
formats or the current locale’s short date format.time
– A time string inHH:MM
orHH: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 methodlocale
– The locale ID that the date and time were formatted in. Defaults to the app’s current formatting locale.timezone
– A valid PHP timezone (opens new window). If set, this will override the assumed timezone per$assumeSystemTimeZone
.
View source (opens new window)
Arguments
$value
(string (opens new window), integer (opens new window), array (opens new window), DateTimeInterface (opens new window), null (opens new window)) – The value that should be converted to a DateTime object.$assumeSystemTimeZone
(boolean (opens new window)) – Whether it should be assumed that the value was set in the system timezone if the timezone was not specified. If this isfalse
, UTC will be assumed.$setToSystemTimeZone
(boolean (opens new window)) – Whether to set the resulting DateTime object to the system timezone.
Returns
DateTime (opens new window), false (opens new window) – The DateTime object, or false
if $object could not be converted to one
Throws
# toIso8601()
Converts a date to an ISO-8601 string.
View source (opens new window)
Arguments
$date
(mixed
) – The date, in any format that toDateTime() supports.
Returns
string (opens new window), false (opens new window) – 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 (opens new window) object set to midnight of the current day (factoring in whether time is paused).
View source (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# tomorrow()
- Since
- 4.3.0
Returns a DateTime (opens new window) object set to midnight of the following day (factoring in whether time is paused).
View source (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# yesterday()
- Since
- 4.3.0
Returns a DateTime (opens new window) object set to midnight of the previous day (factoring in whether time is paused).
View source (opens new window)
Arguments
$timeZone
(DateTimeZone (opens new window), null (opens new window)) – The time zone to return theDateTime
object in. (Defaults to the system time zone.)
Returns
# Constants
Constant | Description |
---|---|
SECONDS_DAY | |
SECONDS_HOUR | |
SECONDS_MINUTE | |
SECONDS_MONTH | |
SECONDS_YEAR |