PHP Velho Oeste 2024
    Edit Report a Bug

    date_parse

    (PHP 5 >= 5.2.0, PHP 7, PHP 8)

    date_parse — Returns associative array with detailed info about given date/time

    Description

    date_parse(string $datetime): array

    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.

    Parameters

    datetime

    Date/time in format accepted by DateTimeImmutable::__construct().

    Return Values

    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.

    Warning

    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.

    Errors/Exceptions

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

    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.

    Examples

    Example #1 A date_parse() example with a comprehensive datetime string

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

    The above example will output:

    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.

    Example #2 date_parse() with timezone abbreviation information

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

    The above example will output:

    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"
}

    Example #3 date_parse() with timezone identifier information

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

    The above example will output:

    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.

    Example #4 date_parse() with a minimal string

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

    The above example will output:

    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.

    Example #5 date_parse() with relative formats

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

    The above example will output:

    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.

    Example #6 date_parse() with side-effects

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

    The above example will output:

    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)
  }
}

    See Also

    • date_parse_from_format() - Get info about given date formatted according to the specified format for parsing a datetime with a specific given format
    • checkdate() - Validate a Gregorian date for Gregorian date validation
    • getdate() - Get date/time information

    add a note add a note

    User Contributed Notes 11 notes

    up
    12
    admin at torntech dot com
    13 years ago
    A warning to others. Some keys will return with a default value where others will return as false if the date string has it omitted. Unsure if this is a bug or feature, but hopefully this will save someone some time.
    <?php
    ///Example
    $input = "Feb 2010";
    $info = date_parse($input);
    var_dump($info);

    /*Returns:
    array(12) {
        ["year"]=> int(2010)
        ["month"]=> int(2)
        ["day"]=> int(1)    //<---expected false like below
        ["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)
    }*/
    ?>
    up
    8
    alvaro at demogracia dot com
    13 years ago
    Be aware that date_parse() is happy with just a time zone and it can be pretty counter-intuitive. E.g.:

    <?php
    var_dump    ( date_parse('Europe/Madrid') );
    ?>

    ... prints an array where year, month, day... are FALSE. But so do these:

    <?php
    var_dump    ( date_parse('A') );
    var_dump( date_parse('B') );
    var_dump( date_parse('X') );
    ?>

    Don't forget to further validate date_parse()'s output even when it isn't FALSE and the 'errors' key is empty.
    up
    1
    edg at greenberg dot org
    5 years ago
    Passing "YYYY-MM" results in a valid date. Be careful to validate that your submitted date passed YOUR requirements.
    up
    1
    paul at juniperwebcraft dot com
    7 years ago
    It's sometimes useful to be able to store incomplete dates, for example when all you know of someone's birthdate is the year or the month and day.

    date_parse() handles (and MySQL accepts) dates containing zero-value elements such as "2017-00-00" and "0000-03-29", leaving it up to the parent application to determine when to require and how to handle missing date elements. date_parse() correctly reports zero values for zero-value date elements, reports an 'invalid date' warning, and does not report an error.

    Example 1: Year only
    <?php print_r( date_parse( '2017-00-00' ) );?>
    generates:
    <?php
    Array
    (
        [    year] => 2017
            [month] => 0
            [day] => 0
            [hour] =>
        [    minute] =>
        [    second] =>
        [    fraction] =>
        [    warning_count] => 1
            [warnings] => Array
            (
                [    11] => The parsed date was invalid
                )

        [    error_count] => 0
            [errors] => Array
            (
            )

        [    is_localtime] =>
    )
    ?>

    Example 2: Month and day only
    <?php print_r( date_parse( '0000-03-29' ) )?>
    generates:
    <?php
    Array
    (
        [    year] => 0
            [month] => 3
            [day] => 29
            [hour] =>
        [    minute] =>
        [    second] =>
        [    fraction] =>
        [    warning_count] => 1
            [warnings] => Array
            (
                [    11] => The parsed date was invalid
                )

        [    error_count] => 0
            [errors] => Array
            (
            )

        [    is_localtime] =>
    )
    ?>

    However, simply omitting date elements gives PHP too much discretion in second-guessing our intentions:

    Example 3: Truncated date:
    <?php print_r( date_parse( '2017-03' ) )?>
    generates:
    <?php
    Array
    (
        [    year] => 2017
            [month] => 3
            [day] => 1
            [hour] =>
        [    minute] =>
        [    second] =>
        [    fraction] =>
        [    warning_count] => 0
            [warnings] => Array
            (
            )

        [    error_count] => 0
            [errors] => Array
            (
            )

        [    is_localtime] =>
    )    ?>
    In this case, PHP supplies a day value of 1 and does not report a warning.

    Similarly, this feature of accepting zero date elements does not carry over to timestamps:

    <?php $dDate = strtotime( '2017-03-00' );
    print_r( getdate( $dDate ) ); ?>

    displays:

    <?php Array
    (
        [    seconds] => 0
            [minutes] => 0
            [hours] => 0
            [mday] => 28
            [wday] => 2
            [mon] => 2
            [year] => 2017
            [yday] => 58
            [weekday] => Tuesday
            [month] => February
            [0] => 1488268800
    )
    ?>
    In this case, PHP interprets the "zeroth" day of March to be the last day of February.
    up
    0
    y dot adounis at gmail dot com
    4 years ago
    Developers, be aware that using "now" will return an empty array, ex :

    <?php
    date_parse    ("now");
    ?>

    Will return :

    Array
    (
        [year] =>
        [month] =>
        [day] =>
        [hour] =>
        [minute] =>
        [second] =>
        [fraction] =>
        [warning_count] => 0
        [warnings] => Array
            (
            )

        [error_count] => 0
        [errors] => Array
            (
            )

        [is_localtime] =>
    )
    up
    0
    ryan_a_martin at yahoo dot com
    13 years ago
    See checkdate() at http://php.net/manual/en/function.checkdate.php for Gregorian date validation.
    up
    0
    gpayne at galenaparkisd com
    16 years ago
    Careful - date_parse is perfectly happy with something like this:

    date_parse("2006-2-31");
    up
    -2
    adamm at extratech dot com
    11 years ago
    A warning to some
    <?php
    $time     = "00:14:38"
    $parse_date = date_parse($time);
    echo     var_dump($parse_date) ."<br>";
    //here you will get what you expect

    $time = "-00:14:38"
    $parse_date = date_parse($time);
    echo     var_dump($parse_date) ."<br>";
    //here you will recieve hours minutes and seconds as booleans and as false and you will get error set to "Unexpected character"

    $time = "00:-14:38"
    $parse_date = date_parse($time);
    echo     var_dump($parse_date) ."<br>";
    //here you will recieve the same as the above

    $time = "00:14:-38"
    $parse_date = date_parse($time);
    echo     var_dump($parse_date) ."<br>";
    //here you will receive hours as 00 minutes as 14 and seconds as 0. The error will get set as the same as above. Meaning "Unexpected character"
    ?>
    up
    -5
    alan at wilcoxengineering dot com
    14 years ago
    Caution: date_parse expects months 1..12 only.

    date_parse("13/1/5769")  for  month=13, Ehul in Jewish calendar, results in  month==3 instead of month==13.

    It does, however, report the error array showing "Unexpected Character."

    It would be nice if date_parse could handle the months properly (just report back a "13" for the month). The older approach of substr() is my workaround.
    up
    -4
    eugene at ultimatecms dot co dot za
    14 years ago
    <?php

    $ida     = '091122671325';
    $idb = '091123671325';

    // This function will match the identity number up to the day, but only for a maximum of 99years+364days.
    // Will not work when checking persons older than 100years-1day.

    function idtodate($id)
    {
                $year = date("Y");
                $month = date("m");
                $day = date("d");

                $nc = substr($year, 0, 2);
                $ny = substr($year, 2, 2);

                $y = substr($id, 0, 2);
                $m = substr($id, 2, 2);
                $d = substr($id, 4, 2);

            if(    $y.$m.$d <= $ny.$month.$day-1) {
                        $newc = $nc;
            } else {
                        $newc = $nc-1;
            }

                $new = $newc.$y;

            return array(    'year' => $new, 'month' => $m, 'day' => $d);
    }

    echo     'ID: '.$ida.'<br>';
    print_r(idtodate($ida));

    echo     '<br><br>';

    echo     'ID: '.$idb.'<br>';
    print_r(idtodate($idb));

    ?>

    Output:
    1. If the year-month-day is smaller than today (2009-11-23), but bigger than 1999: year => 2009
    ID: 091122671325
    Array ( [year] => 2009 [month] => 11 [day] => 22 )

    2. If the year-month-day is the same as, or bigger than today, but smaller than 2000: year => 1909
    ID: 091123671325
    Array ( [year] => 1909 [month] => 11 [day] => 23 )
    add a note add a note
    To Top