DateTime Class

PHP's DateTime class is an object-oriented approach to handling dates and times. It encapsulates all the date and time-related functionality within an object, providing methods to perform various operations.

While traditional date() and time() functions in PHP are still useful and valid, the DateTime class provides a more modern, robust, and versatile way to work with dates and times. It offers advantages in terms of code organization, readability, and extended features. It's particularly beneficial for more complex date and time manipulations and aligns with object-oriented coding practices.

Additional benefits include:

• Using the DateTimeImmutable class prevents modification of the objects, enhancing predictability.
• It simplifies working with different time zones.
• Easy manipulation of dates with methods like add() and sub().
• Provides format() method to convert a DateTime object into a string with a custom format.
• Enables comparison of two DateTime objects with ease.
• Offers additional classes like DateInterval and DatePeriod for more complex operations.

As of PHP 5.2.0, the DateTime class represents a more modern practice in PHP development.

Instantiating the DateTime Class

Creating an instance of the DateTime class is simple and can be done using the new keyword along with the DateTime constructor. You can pass a date string as an argument, and it supports various date formats.

Here's how you can create a DateTime instance for the current date and time:

$datetime = new DateTime();

For a specific date and time:

$datetime = new DateTime('2023-08-04 15:30:00');

Valid Date Formats

The DateTime constructor accepts a wide range of date formats, including but not limited to:

• Standard Formats: Y-m-d, Y/m/d, m-d-Y, d-m-Y, d.m.Y
• Full Date and Time: Y-m-d H:i:s
• Relative Formats: now, +1 day, next Monday, last year
• ISO 8601 Format: Y-m-d\TH:i:sP

Here are some examples:

$datetime1 = new DateTime('2023-08-04'); // Using a standard format
$datetime2 = new DateTime('now'); // Using a relative format
$datetime3 = new DateTime('+3 weeks'); // Using a relative format with arithmetic
$datetime4 = new DateTime('2023-08-04T15:30:00+00:00'); // Using ISO 8601 format

For a complete list of valid formats, view this documentation page: https://www.php.net/manual/en/datetime.formats.php

If an invalid date string is provided, the DateTime constructor will throw an exception, so it's good practice to handle potential exceptions using a try-catch block.

Alternative Solution

An alternative solution to creating an instance of the DateTime class is to use the date_create_from_format() function. The date_create_from_format() function in PHP is used to parse a time string according to a specified format, and it returns a new DateTime object formatted accordingly.

Here's the function definition:

date_create_from_format(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTime|false

Parameters

• $format: The format that the passed time string should be in. This is the pattern to which the $datetime string must conform.
• $datetime: The time string that you want to parse into a DateTime object. It must match the format specified by $format.
• $timezone: (Optional) A DateTimeZone object representing the desired time zone. If not provided, the current time zone will be used.

The function returns a new DateTime object on success or FALSE on failure.

You may be wondering why use it over creating an instance of the DateTime class?

If you have a date string in a specific format and want to ensure that it exactly matches that format, you can use date_create_from_format(). It allows for precise control over the expected format of the input string. Secondly, if you're working with dates from a source that uses a consistent but non-standard format, this function makes it easier to create DateTime objects from those strings without having to reformat them first.

Let's look at a basic example.

$format = 'd-m-Y H:i:s';
$time = '04-08-2023 15:30:00';
$dateTime = date_create_from_format($format, $time);

Formatting the Date

After creating the date, you may want to display it. The DateTime class offers a method for formatting the date in whichever way you want.

Formatting a date with the DateTime class in PHP is straightforward and can be done using the format() method. This method allows you to convert a DateTime object into a string with a custom format.

There's one parameter called $format. The $format parameter specifies the desired output format, using the same format characters as the date() function.

Here's how you can use the format() method:

$datetime = new DateTime('2023-08-04 15:30:00');
$formattedDate = $datetime->format('Y-m-d H:i:s');
 
echo $formattedDate; // Outputs "2023-08-04 15:30:00"

You can use various format characters to customize the output as needed:

echo $datetime->format('l, F j, Y'); // Outputs "Friday, August 4, 2023"
echo $datetime->format('d/m/Y'); // Outputs "04/08/2023"
echo $datetime->format('g:i A'); // Outputs "3:30 PM"

The format() method provides a flexible and powerful way to convert a DateTime object into a human-readable date and time string, using the format characters that meet your specific needs.

Grabbing the Timestamp

You can retrieve the Unix timestamp from a DateTime instance using the getTimestamp() method. This method returns the Unix timestamp representing the same point in time as the DateTime object.

$datetime = new DateTime();
$timestamp = $datetime->getTimestamp();
 
echo $timestamp; // Outputs the Unix timestamp for the specified date and time

Overwritting the Date

You can overwrite the date in a DateTime object by using the setDate() method. This method allows you to change the year, month, and day components of a DateTime object while leaving the time portion unchanged.

Here's the method definition:

DateTime setDate ( int $year , int $month , int $day )

Parameters

• $year: The year as a 4-digit number.
• $month: The month as a number from 1 to 12.
• $day: The day as a number from 1 to 31, depending on the month.

The setDate() method returns the DateTime object itself, so you can chain other DateTime methods if you wish.

Here's an example of how you could use the setDate() method:

$datetime = new DateTime();
$datetime->setDate(2025, 12, 25);
 
echo $datetime->format('Y-m-d H:i:s'); // Outputs "2025-12-25 15:30:00"

In this example, the year, month, and day are changed, but the time remains the same.

The setDate() method does not check for the validity of the provided date (e.g., February 30th). If you provide an invalid date, it will be normalized (e.g., February 30th will become March 2nd in a non-leap year).

Changing the Time

You can overwrite the time in a DateTime object in PHP by using the setTime() method. This method allows you to change the hour, minute, and optionally the second and microsecond components of a DateTime object, leaving the date portion unchanged.

Here's the method definition:

DateTime setTime ( int $hour , int $minute [, int $second = 0 [, int $microseconds = 0 ]] )

Parameters

• $hour: The hour is a number from 0 to 23.
• $minute: The minute is a number from 0 to 59.
• $second: (Optional) The second is a number from 0 to 59. Defaults to 0.
• $microseconds: (Optional) The microsecond is a number from 0 to 999999. Defaults to 0.

The setTime() method returns the DateTime object itself, allowing for method chaining if desired.

Here's an example of how you could use the setTime() method:

$datetime = new DateTime('2023-08-04 15:30:00');
$datetime->setTime(20, 45, 15);
 
echo $datetime->format('Y-m-d H:i:s'); // Outputs "2023-08-04 20:45:15"

In this example, the hour, minute, and second are changed, but the date remains the same.

It's worth noting that the method does not throw an error if the hour, minute, second, or microsecond values are outside their typical ranges. Instead, they are normalized. For example, 90 minutes would be converted to 1 hour and 30 minutes.

Changing the Timestamp

You can change the Unix timestamp of a DateTime object in PHP using the setTimestamp() method. This method sets the date and time based on a Unix timestamp, which is the number of seconds since the Unix Epoch (January 1, 1970, at 00:00:00 UTC).

Here's the method definition:

DateTime setTimestamp ( int $unixtimestamp )

Parameter

• $unixtimestamp: The Unix timestamp representing the new date and time.

The setTimestamp() method returns the DateTime object itself, so you can chain other DateTime methods if you wish. Example Usage

Here's how you can use the setTimestamp() method:

$datetime = new DateTime();
$datetime->setTimestamp(1689783000);
 
echo $datetime->format('Y-m-d H:i:s'); // Outputs the date and time corresponding to the Unix timestamp

The Unix timestamp is always in UTC, so if the DateTime object is set to a different timezone, the setTimestamp() method will adjust the time to that timezone.

Modifying the Date

Modifying the existing date in a DateTime object can be done using the modify(). This method allows you to change the date and time using a relative format string. You can add or subtract days, months, years, etc.

Here's the method definition:

DateTime DateTime::modify ( string $modify )

Parameter

• $modify: A string that defines the date modification. It can describe a relative change (like +2 days or -3 weeks) or an absolute date.

The modify() method returns the DateTime object itself, so you can chain other DateTime methods if you wish.

Here's an example of adding 5 days to the current date:

$datetime = new DateTime();
$datetime->modify('+5 days');

Here's another example of subtracting 1 month from the current date:

$datetime = new DateTime();
$datetime->modify('-1 month');

Here's another example to set to the last day of the current month:

$datetime = new DateTime();
$datetime->modify('last day of this month');

The modify() method supports a wide variety of relative and absolute date formats, including natural language expressions like yesterday, now, first day of January, etc.

Key Takeaways

• You can create a new DateTime object with various formats, including a specific date string or a Unix timestamp.
• Use the format() method to display the date in various formats.
• Change date and time with the modify() method using relative or absolute strings.
• Overwrite the date with the setDate() method.
• Overwrite the time with the setTime() method.
• Change the date and time using a Unix timestamp with the setTimestamp() method.