date_parse

Returns associative array with detailed info about given date/time

&reftitle.description; `array` `date_parse` `string` `datetime`

`date_parse` parses the given `datetime` string according to the same rules as `strtotime` and `DateTimeImmutable::__construct`. Instead of returning a Unix timestamp (with `strtotime`) or a `DateTimeImmutable` object (with `DateTimeImmutable::__construct`), it returns an associative array with the information that it could detect in the given `datetime` string.

If no information about a certain group of elements can be found, these array elements will be set to &false; or are missing. If needed for constructing a timestamp or `DateTimeImmutable` object from the same `datetime` string, more fields can be set to a non-&false; value. See the examples for cases where that happens.

&reftitle.parameters;

`datetime`

- Date/time in format accepted by `DateTimeImmutable::__construct`.

&reftitle.returnvalues;

Returns `array` with information about the parsed date/time.

The returned array has keys for `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction`, and `is_localtime`.

If `is_localtime` is present then `zone_type` indicates the type of timezone. For type `1` (UTC offset) the `zone`, `is_dst` fields are added; for type `2` (abbreviation) the fields `tz_abbr`, `is_dst` are added; and for type `3` (timezone identifier) the `tz_abbr`, `tz_id` are added.

If relative time elements are present in the `datetime` string such as `+3 days`, the then returned array includes a nested array with the key `relative`. This array then contains the keys `year`, `month`, `day`, `hour`, `minute`, `second`, and if necessary `weekday`, and `weekdays`, depending on the string that was passed in.

The array includes `warning_count` and `warnings` fields. The first one indicate how many warnings there were. The keys of elements `warnings` array indicate the position in the given `datetime` where the warning occurred, with the string value describing the warning itself.

The array also contains `error_count` and `errors` fields. The first one indicate how many errors were found. The keys of elements `errors` array indicate the position in the given `datetime` where the error occurred, with the string value describing the error itself.

The number of array elements in the `warnings` and `errors` arrays might be less than `warning_count` or `error_count` if they occurred at the same position.

&reftitle.errors;

In case the date/time format has an error, the element 'errors' will contain the error messages.

&reftitle.changelog;

&Version; | &Description;
7.2.0 | The `zone` element of the returned array represents seconds instead of minutes now, and its sign is inverted. For instance `-120` is now `7200`.

&reftitle.examples;

### A `date_parse` example with a comprehensive `datetime` string

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5"));
    ?>

&example.outputs;

    array(12) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

The timezone elements only show up if they are included in the given `datetime` string. In that case there will always be a `zone_type` element and a few more depending on its value.

### `date_parse` with timezone abbreviation information

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));
    ?>

&example.outputs;

    array(16) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(2)
      ["zone"]=>
      int(0)
      ["is_dst"]=>
      bool(true)
      ["tz_abbr"]=>
      string(3) "BST"
    }

### `date_parse` with timezone identifier information

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));
    ?>

&example.outputs;

    array(14) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(3)
      ["tz_id"]=>
      string(13) "Europe/London"
    }

If a more minimal `datetime` string is parsed, less information is available. In this example, all the time parts are returned as &false;.

### `date_parse` with a minimal string

    <?php
    var_dump(date_parse("June 2nd, 2022"));
    ?>

&example.outputs;

    array(12) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      bool(false)
      ["minute"]=>
      bool(false)
      ["second"]=>
      bool(false)
      ["fraction"]=>
      bool(false)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Relative formats do not influence the values parsed from absolute formats, but are parsed into the "relative" element.

### `date_parse` with relative formats

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));
    ?>

&example.outputs;

    array(13) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(6) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(7)
        ["hour"]=>
        int(1)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
      }
    }

Some stanzas, such as `Thursday` will set the time portion of the string to `0`. If `Thursday` is passed to `DateTimeImmutable::__construct` it would also have resulted in the hour, minute, second, and fraction being set to `0`. In the example below, the year element is however left as &false;.

### `date_parse` with side-effects

    <?php
    var_dump(date_parse("Thursday, June 2nd"));
    ?>

&example.outputs;

    array(13) {
      ["year"]=>
      bool(false)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(0)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(7) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["weekday"]=>
        int(4)
      }
    }

&reftitle.seealso;

- `date_parse_from_format` for parsing a `datetime` with a specific given format
- `checkdate` for Gregorian date validation
- `getdate`