Relative Formats
This page describes the different relative date/time formats that the DateTimeImmutable, DateTime, date_create(), date_create_immutable(), and strtotime() parser understands.
Description | Format |
---|---|
dayname |
'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' |
daytext |
'weekday' | 'weekdays' |
number |
[+-]?[0-9]+ |
ordinal |
'first' | 'second' | 'third' | 'fourth' | 'fifth' | 'sixth' | 'seventh' | 'eighth' | 'ninth' | 'tenth' | 'eleventh' | 'twelfth' | 'next' | 'last' | 'previous' | 'this' |
reltext |
'next' | 'last' | 'previous' | 'this' |
space |
[ \t]+ |
unit |
'ms' | 'µs' | (( 'msec' | 'millisecond' | 'µsec' | 'microsecond'
| 'usec' | 'sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' |
'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' |
daytext |
Format | Description | Examples |
---|---|---|
'yesterday' | Midnight of yesterday | "yesterday 14:00" |
'midnight' | The time is set to 00:00:00 | |
'today' | The time is set to 00:00:00 | |
'now' | Now - this is simply ignored | |
'noon' | The time is set to 12:00:00 | "yesterday noon" |
'tomorrow' | Midnight of tomorrow | |
'back of' hour |
15 minutes past the specified hour | "back of 7pm", "back of 15" |
'front of' hour |
15 minutes before the specified hour | "front of 5am", "front of 23" |
'first day of' | Sets the day of the first of the current month. This phrase is usually best used together with a month name following it as it only effects the current month | "first day of January 2008" |
'last day of' | Sets the day to the last day of the current month. This phrase is usually best used together with a month name following it as it only effects the current month | "last day of next month" |
ordinal space dayname space 'of' |
Calculates the x -th week day of the current month. |
"first sat of July 2008" |
'last' space dayname space 'of' |
Calculates the last week day of the current month. | "last sat of July 2008" |
number space ? (unit | 'week') |
Handles relative time items where the value is a number. | "+5 weeks", "12 day", "-7 weekdays" |
ordinal space unit |
Handles relative time items where the value is text. | "fifth day", "second month" |
'ago' | Negates all the values of previously found relative time items. | "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago" |
dayname |
Moves to the next day of this name. (See note) | "Monday" |
reltext space 'week' |
Handles the special format "weekday + last/this/next week". | "Monday next week" |
Note:
Relative statements are always processed after non-relative statements. This makes "+1 week july 2008" and "july 2008 +1 week" equivalent.
Exceptions to this rule are: "yesterday", "midnight", "today", "noon" and "tomorrow". Note that "tomorrow 11:00" and "11:00 tomorrow" are different. Considering today's date of "July 23rd, 2008" the first one produces "2008-07-24 11:00" where as the second one produces "2008-07-24 00:00". The reason for this is that those five statements directly influence the current time.
Keywords such as "first day of" depend on the context in which the relative format string is used. If used with a static method or function, the referent is the current system timestamp. However, if used in DateTime::modify() or DateTimeImmutable::modify(), the referent is the object on which the
modify()
method is called.
Note:
Observe the following remarks when the current day-of-week is the same as the day-of-week used in the date/time string. The current day-of-week could have been (re-)calculated by non-relative parts of the date/time string however.
- "
dayname
" does not advance to another day. (Example: "Wed July 23rd, 2008" means "2008-07-23").- "
number
dayname
" does not advance to another day. (Example: "1 wednesday july 23rd, 2008" means "2008-07-23").- "
number
weekdayname
" will first add the number of weeks, but does not advance to another day. In this case "number
week" and "dayname
" are two distinct blocks. (Example: "+1 week wednesday july 23rd, 2008" means "2008-07-30").- "
ordinal
dayname
" does advance to another day. (Example "first wednesday july 23rd, 2008" means "2008-07-30").- "
number
weekordinal
dayname
" will first add the number of weeks, and then advances to another day. In this case "number
week" and "ordinal
dayname
" are two distinct blocks. (Example: "+1 week first wednesday july 23rd, 2008" means "2008-08-06").- "
ordinal
dayname
'of' " does not advance to another day. (Example: "first wednesday of july 23rd, 2008" means "2008-07-02" because the specific phrase with 'of' resets the day-of-month to '1' and the '23rd' is ignored here).Also observe that the "of" in "
ordinal
space
dayname
space
'of' " and "'last'space
dayname
space
'of' " does something special.
- It sets the day-of-month to 1.
- "
ordinal
dayname
'of' " does not advance to another day. (Example: "first tuesday of july 2008" means "2008-07-01").- "
ordinal
dayname
" does advance to another day. (Example: "first tuesday july 2008" means "2008-07-08", see also point 4 in the list above).- "'last'
dayname
'of' " takes the lastdayname
of the current month. (Example: "last wed of july 2008" means "2008-07-30")- "'last'
dayname
" takes the lastdayname
from the current day. (Example: "last wed july 2008" means "2008-06-25"; "july 2008" first sets the current date to "2008-07-01" and then "last wed" moves to the previous Wednesday which is "2008-06-25").
Note:
Relative month values are calculated based on the length of months that they pass through. An example would be "+2 month 2011-11-30", which would produce "2012-01-30". This is due to November being 30 days in length, and December being 31 days in length, producing a total of 61 days.
Note:
number
is an integer number; if a decimal number is given, the dot (or comma) is likely interpreted as delimiter. For instance,'+1.5 hours'
is parsed like'+1 5 hours'
, not as'+1 hour +30 minutes'
.
Changelog
Version | Description |
---|---|
7.0.8 | Weeks always start on monday. Formerly, sunday would also be considered to start a week. |