PHP Function date_time_set()

In PHP, the DateTime::setTime() method is used to set a new time for a given DateTime object. This method is part of the PHP DateTime class and can be used to set the time portion of a date/time object to a new value.

Syntax

The syntax for the DateTime::setTime() method is as follows:

The syntax for the DateTime::setTime() method

$datetime->setTime($hour, $minute, $second, $microsecond);

Where:

• $datetime is the DateTime object to modify.
• $hour is the new hour value (0–23).
• $minute is the new minute value (0–59).
• $second is the new second value (0–59, optional, default is 0).
• $microsecond is the new microsecond value (0–999999, optional, default is 0).

Note: The timezone of the DateTime object is preserved during this operation. The method modifies the object in place. If provided values exceed their valid ranges, PHP automatically normalizes them (e.g., hour 25 rolls over to the next day) rather than throwing an exception.

Example Usage

Let's take a look at an example of how to use the DateTime::setTime() method:

Example of PHP DateTime::setTime() Method

In this example, we first create a new DateTime object with the date and time set to '2000-01-01 12:00:00'. We then use the setTime() method to set the hour to 14 and the minute to 30. Finally, we use the format() method to display the modified date and time in the format 'Y-m-d H:i:s'. The output is:

2000-01-01 14:30:00

Because we did not pass $second or $microsecond, both default to 0, so the seconds are reset even though the original time had :00 seconds.

Setting Seconds and Microseconds

You can pass all four arguments to control the time down to the microsecond. The microsecond component only shows up in the output if your format string includes u:

<?php
$date = new DateTime('2000-01-01 12:00:00');
$date->setTime(14, 30, 15, 500000);
echo $date->format('Y-m-d H:i:s.u');

This prints 2000-01-01 14:30:15.500000.

Out-of-Range Values Roll Over

setTime() does not throw on values outside the valid range — it normalizes them and carries the overflow into the date. Setting the hour to 25 pushes the date forward by one day:

<?php
$date = new DateTime('2000-01-01 23:30:00');
$date->setTime(25, 0);
echo $date->format('Y-m-d H:i:s');

This prints 2000-01-02 01:00:00 — hour 25 becomes 01:00 on the next day. This is handy for arithmetic (e.g. "add 5 hours" by passing $hour + 5), but a source of silent bugs if you expected validation. To change the date directly instead, use setDate(), or modify() for relative shifts.

How DateTime::setTime() Compares to Other Functions

The DateTime::setTime() method is the standard object-oriented approach in PHP for modifying time. Unlike procedural date functions that return new strings or require complex parsing, setTime() directly modifies the DateTime object in place, ensuring type safety and consistent behavior.

This contrasts with DateTimeImmutable::setTime(), which returns a new instance and leaves the original untouched:

<?php
$original = new DateTimeImmutable('2000-01-01 12:00:00');
$changed  = $original->setTime(8, 0);

echo $original->format('H:i'), ' | ', $changed->format('H:i');

This prints 12:00 | 08:00: $original is unchanged, and $changed holds the new time. With the mutable DateTime, the call returns the same object it modified, so $original and $changed would point at one 08:00 object. Prefer DateTimeImmutable when a value is shared or passed around, to avoid accidental mutation.

Related methods you may reach for alongside setTime(): setDate() to change the year/month/day, setTimezone() to convert to another zone, and date_default_timezone_set() to set the script-wide default. To create the object in the first place, see new DateTime.

Conclusion

The DateTime::setTime() method is a useful tool for manipulating dates and times in PHP. By providing a straightforward way to update the time portion of a DateTime object, it offers a convenient and reliable approach for date/time manipulation. For immutable date handling, use DateTimeImmutable::setTime(), which returns a new instance instead of modifying the original.

Practice