Date Parsing in PHP

Dates often arrive as plain strings — from a form input, a CSV file, or an API response — and PHP has no way to know how those strings are laid out unless you tell it. The date_parse_from_format() function lets you parse a date string against an explicit format and inspect the result, including any errors or warnings. This page covers how the function works, how to read its return value, how to validate input, and when to reach for a different tool such as DateTime or strtotime() instead.

What date parsing means

Date parsing is the process of turning a string like "2023-03-03" into structured data — a year, a month, a day, and so on — that your program can work with. The hard part is ambiguity: 03/04/2023 could be the 4th of March or the 3rd of April depending on the convention, and 2023-13-45 looks like a date but is not a valid one.

date_parse_from_format() removes that ambiguity by requiring you to supply the exact format up front. It reads the string strictly according to that format and tells you what it found, so you can decide whether the input was valid.

The date_parse_from_format() function

date_parse_from_format() parses a date string using a specific format and returns an associative array describing the parsed date: year, month, day, hour, minute, second, plus warnings and errors collected while reading the string.

Syntax

date_parse_from_format(string $format, string $datetime): array

• $format — a format string using the same placeholders as date(), for example Y-m-d for 2023-03-03 or d/m/Y for 03/03/2023.
• $datetime — the date string to parse.

The function always returns an array; it never throws. To know whether parsing succeeded you must check the error_count and warning_count keys.

A basic example

The output of this code will be:

Array
(
    [year] => 2023
    [month] => 3
    [day] => 3
    [hour] => 10
    [minute] => 30
    [second] => 0
    [fraction] => 
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] => 
    [zone_type] => 1
    [zone] => -14400
    [is_dst] => 
)

The function parsed "2023-03-03 10:30:00" against the format Y-m-d H:i:s and filled in each component. You can read individual values directly from the array, such as $date_array['year'] or $date_array['month']. When a component is absent from the format string, its value comes back as false (rendered as an empty value by print_r).

Parsing custom formats

The format placeholders are the same ones used by date(), so any layout you can produce, you can also parse. The example below reads a European-style day/month/year date:

<?php

$result = date_parse_from_format("d/m/Y", "03/03/2023");

echo "Day:   {$result['day']}\n";
echo "Month: {$result['month']}\n";
echo "Year:  {$result['year']}\n";

This prints:

Day:   3
Month: 3
Year:  2023

Because only d, m, and Y appear in the format, the hour, minute, and second keys come back as false.

Validating the result: errors and warnings

date_parse_from_format() never throws an exception — even on bad input it returns an array. Two keys tell you whether the input was usable:

• error_count counts characters that did not match the format at all.
• warning_count counts values that matched the format but make no sense, such as month 13 or day 45.

A string that does not match the format produces errors:

<?php

// Expecting Y-m-d but the input is d/m/Y
$result = date_parse_from_format("Y-m-d", "03/03/2023");

echo "Errors:   {$result['error_count']}\n";
print_r($result['errors']);

Errors:   5
Array
(
    [2] => Unexpected data found.
    [5] => Unexpected data found.
    [8] => Trailing data
)

A string that matches the format but is not a real date produces a warning instead:

<?php

$result = date_parse_from_format("Y-m-d", "2023-13-45");

echo "Warnings: {$result['warning_count']}\n";
print_r($result['warnings']);

Warnings: 1
Array
(
    [10] => The parsed date was invalid
)

Always check both counts before trusting the parsed values:

if ($result['error_count'] === 0 && $result['warning_count'] === 0) {
    // safe to use $result['year'], $result['month'], etc.
}

When to use a different function

date_parse_from_format() is best when you want a detailed, format-aware report — especially to validate input. If you just need a usable date value, other tools are more convenient:

• DateTime::createFromFormat($format, $string) returns a ready-to-use DateTime object you can format or do arithmetic on. See PHP date and time.
• strtotime() guesses the format for you and returns a Unix timestamp — handy for common, unambiguous strings, but riskier for locale-specific layouts.
• date_parse() is the same as this function but without a format string; it tries to interpret the date on its own.

Conclusion

date_parse_from_format() parses a date string against an explicit format and returns a detailed associative array, making it ideal for validating user-supplied dates. Remember that it never throws — check error_count and warning_count before using the result. When you need a DateTime object or a timestamp instead, reach for DateTime::createFromFormat() or strtotime().

Practice