date_format()

Purpose

date_format() converts a date-time object into a string. You choose the layout with a format string made of special letters such as Y for the year or H for the hour. It is the procedural alias of DateTime::format(), so date_format($d, 'Y-m-d') and $d->format('Y-m-d') do the same work. Use whichever style matches the rest of your code.

Signature

Parameters and defaults

• $object: a DateTime, DateTimeImmutable or any other DateTimeInterface implementation. Objects usually come from date_create(), date_create_immutable() or a constructor. There is no default.
• $format: the pattern that describes the output. There is no default either; both arguments are required.

Common format characters:

• Year: Y (four digits), y (two digits)
• Month: m (01–12), n (1–12), M (Jan), F (January)
• Day: d (01–31), j (1–31), D (Mon), l (Monday), N (1 for Monday to 7 for Sunday)
• Time: H (00–23), G (0–23), h and g (12-hour clock), i (minutes), s (seconds), A (AM/PM)
• Zone: e (identifier), T (abbreviation), P (offset such as +05:30)
• Other: L (1 in a leap year), t (days in the month), U (Unix timestamp)

The DATE_ATOM constant and its relatives hold ready-made format strings for common standards.

Return value and failures

The function returns a string. The object is not changed, even for a mutable DateTime. A bad format does not produce an error: characters that have no meaning are copied to the output unchanged. An empty format gives an empty string.

The usual failure happens before the call. date_create() returns false when it cannot parse its input. If you pass that false straight to date_format(), PHP throws a TypeError, because the first argument must be a DateTimeInterface. Check the result of date_create() first, or use the constructor and catch the exception it throws.

Example 1: basic layouts

The timezone is set to UTC so the result never depends on the environment.

<?php
date_default_timezone_set('UTC');
$date = date_create('2024-03-15 14:30:45');
echo date_format($date, 'Y-m-d H:i:s'), "\n";
echo date_format($date, 'D, d M Y'), "\n";

2024-03-15 14:30:45
Fri, 15 Mar 2024

The same object is formatted twice with different patterns. Both calls read the same stored moment.

Example 2: unpadded values, escaping and constants

<?php
$date = new DateTimeImmutable('2024-12-05 09:07:03', new DateTimeZone('UTC'));
echo date_format($date, 'j/n/y g:i A'), "\n";
echo date_format($date, '\T\o\d\a\y \i\s l'), "\n";
echo date_format($date, DATE_ATOM), "\n";

5/12/24 9:07 AM
Today is Thursday
2024-12-05T09:07:03+00:00

j, n and g drop leading zeros. A backslash before a letter makes it literal, so \T\o\d\a\y prints the word "Today". The single quotes in PHP keep each backslash intact. DATE_ATOM produces an ISO 8601 style string with the offset.

Example 3: formatting after a timezone change

<?php
$date = new DateTime('2024-07-01 12:00:00', new DateTimeZone('UTC'));
date_timezone_set($date, new DateTimeZone('+05:30'));
echo date_format($date, 'Y-m-d H:i P'), "\n";

2024-07-01 17:30 +05:30

A date-time object holds an instant plus a timezone. Changing the zone changes the displayed wall-clock time, and date_format() reports the object's current zone. Here 12:00 UTC becomes 17:30 at an offset of +05:30.

Edge cases

• Unrecognized letters are not errors. A format such as 'Y-m-d Q' prints the year, month and day followed by a literal Q. Escape any letter that you want to appear as text, or you may get an unexpected value.
• Both DateTime and DateTimeImmutable are accepted, and neither is modified by formatting.
• Month and weekday names come out in English, not in the user's language.
• t and L depend on the actual date, so they are useful for checking month lengths and leap years.
• U returns the Unix timestamp as a string of digits, regardless of the object's timezone.

Common mistakes

1. Mixing up m and i. Month is m, minutes are i. Writing Y-m-d H:m:s prints the month where the minutes should be.
2. Using h for 24-hour time. h is the 12-hour clock with a leading zero. Use H for 00–23.
3. Forgetting to escape literal text. Words like "at" contain a, which means am/pm. Escape each letter with a backslash.
4. Assuming a double-quoted string keeps backslashes. In double quotes you may need \\T to get the right sequence. Single quotes are usually easier.
5. Passing an unchecked date_create() result. A false value triggers a TypeError.
6. Relying on the default timezone. If you do not set a zone, the output depends on configuration. Set it explicitly for reproducible results.

Related functions

• DateTime::format(): the method form of this function.
• date(): formats a Unix timestamp with the same format characters.
• date_create() and date_create_immutable(): build the objects you pass in.
• date_timezone_set(): changes the zone before you format.
• date_default_timezone_set(): sets the default zone used for new objects.
• DateTime::createFromFormat(): the reverse direction, which parses text using a format.

Recap

date_format() takes a DateTimeInterface object and a format string and returns the formatted text. It is an alias of DateTime::format(). Pick the format letters carefully, escape literal characters, set the timezone explicitly, and make sure the object is valid before you format it.