When working with PHP, you may need to strictly parse formatted text into an immutable date-time. This guide explains the operation, shows what its arguments mean, and uses three separate examples to make the result easier to understand.
date_create_immutable_from_format: The format explicitly describes expected fields, and the resulting object cannot be modified in place.
What Is date_create_immutable_from_format in PHP?
Strictly parse formatted text into an immutable date-time. The format explicitly describes expected fields, and the resulting object cannot be modified in place.
Syntax:
date_create_immutable_from_format(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTimeImmutable|false
Parameters and return value: The signature above identifies the arguments and return type where the API has a single call. For topic guides, follow the sequence of calls in the examples. Always distinguish a returned value from an object or variable modified by reference.
Important: Check getLastErrors() for warnings, not only a false return value.
Example 1: Basic Usage
This example introduces the operation with a short and predictable input.
<?php
$date = date_create_immutable_from_format("!Y-m-d", "2026-10-16", new DateTimeZone("UTC"));
echo $date->format(DATE_ATOM);
Output:
2026-10-16T00:00:00+00:00
The code focuses on the main operation. The format explicitly describes expected fields, and the resulting object cannot be modified in place.
Example 2: Another Case
Now compare a different input, locale, date, or option to see another part of the behavior.
<?php
$date = date_create_immutable_from_format("!d/m/Y", "16/10/2026", new DateTimeZone("UTC"));
echo $date->format("Y-m-d");
Output:
2026-10-16
What changes? Check getLastErrors() for warnings, not only a false return value.
Practical Example: Applying It in an Application
Use the following separate example as a starting point for a small application task. Check any extension or environment requirements below before running it.
<?php
$input = "2026-12-31";
$date = date_create_immutable_from_format("!Y-m-d", $input, new DateTimeZone("UTC"));
$errors = DateTimeImmutable::getLastErrors();
if ($date === false || ($errors !== false && ($errors["error_count"] > 0 || $errors["warning_count"] > 0))) {
throw new InvalidArgumentException("Invalid date");
}
echo $date->format(DATE_ATOM);
Output:
2026-12-31T00:00:00+00:00
The practical example demonstrates how to apply this operation to multiple values, a reusable task, or a validated input. The format explicitly describes expected fields, and the resulting object cannot be modified in place.
Important Behavior and Edge Cases
- Core behavior: The format explicitly describes expected fields, and the resulting object cannot be modified in place.
- Inputs and results: Check getLastErrors() for warnings, not only a false return value.
- Alternatives: DateTimeImmutable::createFromFormat() is the object-oriented form.
Comparison With Related Functions
| Function or Approach | When to Use It |
|---|---|
date_create_immutable_from_format | Strictly parse formatted text into an immutable date-time. |
| Related PHP approach | DateTimeImmutable::createFromFormat() is the object-oriented form. |
Common Beginner Mistakes
| Mistake | Correct Approach |
|---|---|
| Using an incorrect input or option | Check getLastErrors() for warnings, not only a false return value. |
| Confusing this API with a related operation | DateTimeImmutable::createFromFormat() is the object-oriented form. |
| Assuming output is identical across environments | Check return values and required extensions or versions. Use explicit locale, timezone or encoding settings when they affect the result. |
Key Takeaways
- date_create_immutable_from_format helps you strictly parse formatted text into an immutable date-time.
- The format explicitly describes expected fields, and the resulting object cannot be modified in place.
- Check getLastErrors() for warnings, not only a false return value.
Use date_create_immutable_from_format when you need to strictly parse formatted text into an immutable date-time. Start with the first example, compare the second, and adapt the practical example to your inputs. Confirm the return value and environment requirements before adding it to production code.