date_format()

date_format()

Introduction

Dates and times are everywhere in real applications: timestamps on blog posts, order dates in an online shop, log entries, calendar events. PHP stores these moments internally in a way that isn't human-readable, so you need a way to turn a date object into a string a person can read — "2023-03-03", "Friday, March 3rd", or "03/03/2023 1:00 PM". That is exactly what date_format() does.

This chapter covers what date_format() is, its syntax, the most useful format characters, and the gotchas around timezones and immutability.

What is the date_format() function?

The date_format() function formats a DateTime object as a string according to a pattern you provide. It is a procedural alias for the object-oriented DateTime::format() method — both produce identical results, so use whichever style fits your codebase:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

// These two lines are equivalent
echo date_format($date, 'Y-m-d');   // procedural
echo $date->format('Y-m-d');        // object-oriented

Syntax

date_format(DateTimeInterface $object, string $format): string

• $object — a DateTime (or DateTimeImmutable) instance. This is the date you want to render.
• $format — a string built from format characters (such as Y, m, d). Any character that is not a format character is printed literally.
• Return value — the formatted date as a string.

How to use the date_format() function

First create a date object with the DateTime class, which is built into PHP:

<?php

$date = new DateTime('2023-03-03');

This creates a date set to March 3, 2023, at midnight. By default, DateTime uses the server's configured timezone — which means the same code can produce different output on different machines. For predictable results, always set the timezone explicitly:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

Now format it however you like:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'Y-m-d');
// Output: 2023-03-03

For modern PHP applications, prefer DateTimeImmutable over DateTime. Methods like modify() mutate a DateTime in place, which is a common source of bugs when the object is passed around; DateTimeImmutable returns a new object instead and works with date_format() in exactly the same way:

<?php

$date = new DateTimeImmutable('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'd/m/Y');
// Output: 03/03/2023

Common date formats

There are many different ways to format dates using the date_format() function. Here are some of the most common formats:

• Y-m-d: The date in YYYY-MM-DD format.
• d/m/Y: The date in DD/MM/YYYY format.
• m/d/Y: The date in MM/DD/YYYY format.
• H:i:s: The time in 24-hour format (e.g., 13:00:00).
• h:i:s a: The time in 12-hour format (e.g., 01:00:00 am).

Format characters

In addition to the common formats above, you can build your own pattern from individual format characters. Here are the ones you will reach for most often:

• Y: The year in four digits (e.g., 2023).
• y: The year in two digits (e.g., 23).
• m: The month as a two-digit number (e.g., 03).
• M: The abbreviated month name (e.g., Mar).
• F: The full month name (e.g., March).
• d: The day of the month as a two-digit number (e.g., 03).
• D: The abbreviated day name (e.g., Fri).
• l: The full day name (e.g., Friday).
• j: The day of the month without leading zeros (e.g., 3).
• S: English ordinal suffix for the day of the month (e.g., st, nd, rd, th).
• H: The hour in 24-hour format (e.g., 13).
• h: The hour in 12-hour format (e.g., 01).
• i: The minutes as a two-digit number (e.g., 05).
• s: The seconds as a two-digit number (e.g., 30).
• a: am or pm.

For the full list of every supported character, see PHP date and time and the date() chapter — date_format() uses the same characters.

Here's an example of a custom date format:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'l, F jS Y, h:i:s a');
// Output: Friday, March 3rd 2023, 12:00:00 am

To print a format character literally instead of having it interpreted, escape it with a backslash:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, '\T\o\d\a\y \i\s l');
// Output: Today is Friday

date_format() vs date()

Both functions format dates, but they take different inputs:

• date() works on a Unix timestamp (an integer) and defaults to "now". Use it for quick, timezone-agnostic formatting: date('Y-m-d').
• date_format() works on a DateTime object, so it carries its own timezone and supports arithmetic (adding days, computing differences) before you format. Use it when you need to manipulate the date.

If you have a string like "3 March 2023", build a DateTime first — date_create_from_format() and strtotime() are the usual entry points.

Conclusion

The date_format() function in PHP provides a straightforward way to format a DateTime object as a readable string. By understanding the available format characters and best practices — setting the timezone explicitly and preferring DateTimeImmutable — you can ensure accurate, predictable date output across every environment your code runs in.

Practice