English
English
In PHP, processing dates and times is a very common requirement in development. PHP provides a variety of ways to create and manipulate date and time objects, among which the DateTimeImmutable class and the date_create_immutable() function are two more important and practical tools. Many developers tend to confuse the relationship between the two when using them. This article will explain in detail the connection and differences between them to help you better understand and use them.
DateTimeImmutable is a built-in class in PHP that represents date and time objects. Unlike the DateTime class, an instance of DateTimeImmutable cannot be modified once it is created. All operations that modify date and time will return a new DateTimeImmutable object instead of modifying the original object itself.
This brings obvious advantages: it ensures the immutability of the object, avoids program errors caused by accidental modification of the object, and makes the code more robust and easy to maintain.
$date = new DateTimeImmutable('2025-05-29');
$newDate = $date->modify('+1 day');
echo $date->format('Y-m-d'); // Output 2025-05-29
echo $newDate->format('Y-m-d'); // Output 2025-05-30
As can be seen from the above code, the $date object itself has not changed, and the modify() method returns a new object.
date_create_immutable() is a function provided by PHP to create an instance of the DateTimeImmutable class. It is a convenient encapsulation of the DateTimeImmutable class constructor.
The function is defined as follows:
function date_create_immutable(string $time = "now", ?DateTimeZone $timezone = null): DateTimeImmutable
It accepts time string and time zone parameters and returns a DateTimeImmutable object.
$date = date_create_immutable('2025-05-29 12:00:00');
echo get_class($date); // Output DateTimeImmutable
Core contact : The date_create_immutable() function is actually a convenient function used to create a DateTimeImmutable object, which is equivalent to executing new DateTimeImmutable() .
The same function : calling date_create_immutable('time') is exactly the same as executing new DateTimeImmutable('time') , both generate an immutable date and time object.
Convenience : Using functions, sometimes the code looks more concise and also facilitates the use of function call methods in certain environments or libraries.
Understanding the importance of immutability
The main purpose of using DateTimeImmutable and its related functions is to avoid accidental modification of object state. You should choose when you want to make sure that the date-time object remains unchanged throughout the life cycle.
Choose how to create an object
If you like object-oriented writing, you can directly use new DateTimeImmutable() .
If you want the code to be more functional, or want to be compatible with some frameworks that only accept function calls, you can use date_create_immutable() .
Avoid confusion
Don't mistake date_create_immutable() for a normal function that returns a string or an array. It always returns a DateTimeImmutable object, and all its methods can be called.
With DateTimeImmutable operation
You can use date_create_immutable() to create an object, and then operate the date through all methods provided by the immutable class, such as modify() , add() , sub() , etc. These operations will return a new object.
DateTimeImmutable is a date-time immutable class of PHP, and the object cannot be modified.
date_create_immutable() is a convenient factory function used to quickly create DateTimeImmutable objects.
Use them to write safer, maintainable code.
There is no difference between the two in essence. Which creation method to choose depends on your coding habits and needs.
For more details, please check the official PHP documentation:
https://gitbox.net/manual/en/class.datetimeimmutable.php
https://gitbox.net/manual/en/function.date-create-immutable.php
