Supported Date and Time Formats

Table of Contents

This section describes all the different formats in a BNF-like format, that the DateTimeImmutable, DateTime, date_create_immutable(), date_create(), date_parse(), and strtotime() parser understands. The formats are grouped by section. In most cases formats from different sections, separated by whitespace, comma or dot, can be used in the same date/time string. For each of the supported formats, one or more examples are given, as well as a description for the format. Characters in single quotes in the formats are case-insensitive ('t' could be t or T), characters in double quotes are case-sensitive ("T" is only T).

To format DateTimeImmutable and DateTime objects, please refer to the documentation of the DateTimeInterface::format() method.

A general set of rules should be taken into account.

  1. The parser, allows for each unit (year, month, day, hour, minute, second) the full range of values. For a year that's just 4 digits, for a month that's 0-12, day is 0-31, hour is 0-24, and minute is 0-59.
  2. 60 is allowed for seconds, as sometimes date strings with that leapsecond do show up. But PHP implements Unix time where "60" is not a valid second number and hence it overflows.
  3. strtotime() returns false if any number is outside of the ranges, and DateTimeImmutable::__construct() throws an exception.
  4. If a string contains a date, all time elements are reset to 0.
  5. All less-significant time elements are reset to 0 if any part of a time is present in the given string.
  6. The parser is dumb, and doesn't do any checks to make it faster (and more generic).

  7. There is an additional check if an invalid date is provided:

    <?php
    $res     = date_parse("2015-09-31");
    var_dump($res["warnings"]);
    ?>

    The above example will output:

    array(1) {
  [11] =>
  string(27) "The parsed date was invalid"
}

  8. It is already possible to handle the edge cases, but then DateTimeImmutable::createFromFormat() must be used while supplying the correct format.

    <?php
    $res     = DateTimeImmutable::createFromFormat("Y-m-d", "2015-09-34");
    var_dump($res);

    The above example will output:

    object(DateTimeImmutable)#1 (3) {
  ["date"]=>
  string(26) "2015-10-04 17:24:43.000000"
  ["timezone_type"]=>
  int(3)
  ["timezone"]=>
  string(13) "Europe/London"
}