date_parse()

Introduction

The date_parse() function in PHP takes a human-readable date string and breaks it down into its individual components — year, month, day, hour, minute, second — returning them as an associative array. Crucially, it also reports any warnings and errors it found while interpreting the string, which makes it a useful tool for validating date input before you act on it.

Unlike strtotime(), which collapses a date string into a single Unix timestamp, date_parse() keeps every part separate and never throws away the diagnostics. That distinction is the main reason to reach for it: when you need to know not just what a date is, but whether the input was actually a valid date.

This page covers the syntax, the full shape of the returned array, how to read warnings and errors, and how date_parse() compares to related functions.

Syntax

date_parse(string $datetime): array

It always returns an array (it never returns false); when parsing fails, the failure is described in the errors key rather than signalled by the return value.

Parameters

$datetime — a string representing the date/time to be parsed. It accepts the same flexible formats understood by PHP's internal date parser, for example:

• '2022-03-03 15:30:45' — full ISO-style date and time
• 'July 4, 2023' — natural language
• 'now', 'tomorrow', '+1 week' — relative expressions

If a component is absent from the string (for instance, no time is given), its key is returned as an empty value rather than being omitted.

Return Value

The function returns an associative array with the following keys:

• year, month, day — the date components (integers, or empty if not present)
• hour, minute, second — the time components (integers, or empty if not present)
• fraction — the fractional part of the seconds (a float, e.g. 0)
• warning_count — the number of warnings generated during parsing
• warnings — an array of warnings, keyed by the character position in the input
• error_count — the number of errors generated during parsing
• errors — an array of errors, keyed by the character position in the input
• is_localtime — whether the string contained timezone information

When is_localtime is true, additional keys such as zone_type, zone, and is_dst describe the timezone.

Basic Example

Let's parse a complete date-and-time string:

Output:

Array
(
    [year] => 2022
    [month] => 3
    [day] => 3
    [hour] => 15
    [minute] => 30
    [second] => 45
    [fraction] => 0
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] =>
)

Each component is now available individually — for example, $date_arr['month'] is 3. Because error_count and warning_count are both 0, we know the string was a clean, valid date.

Parsing a Partial Date

date_parse() does not require a complete date. If you pass only a date with no time, the time keys come back empty:

<?php

$result = date_parse('July 4, 2023');
echo "Year: {$result['year']}\n";
echo "Month: {$result['month']}\n";
echo "Day: {$result['day']}\n";
echo "Hour: '{$result['hour']}'\n"; // empty — no time was given

Output:

Year: 2023
Month: 7
Day: 4
Hour: ''

This is handy when you accept dates without times and want the individual pieces without writing a custom parser.

Detecting Invalid Dates with Warnings

This is where date_parse() shines. Consider February 30th — a date that does not exist. The parser will still return values, but it flags the problem in warnings:

<?php

$result = date_parse('2023-02-30');

if ($result['warning_count'] > 0) {
    foreach ($result['warnings'] as $position => $message) {
        echo "Warning at position $position: $message\n";
    }
}

Output:

Warning at position 11: The parsed date was invalid

Always check error_count (the string could not be understood at all) and warning_count (the string was understood but describes an impossible date) before trusting the parsed components. For a strict yes/no calendar check on a specific year-month-day, pair this with checkdate().

When to Use date_parse() vs. Related Functions

If you later need to render a date, see date() for formatting the components into a string.

Conclusion

The date_parse() function provides a straightforward way to break a date string into its individual components while reporting any warnings and errors along the way. That dual role — extraction and validation — makes it especially useful for checking user-supplied dates before processing them. Combine it with checkdate() for strict validation, or with strtotime() and DateTime when you need timestamps or full date objects.

Practice