Returns date formatted according to given format

Description

Object-oriented style

public DateTimeInterface::format(string $format): string

public DateTimeImmutable::format(string $format): string

public DateTime::format(string $format): string

Procedural style

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

Returns date formatted according to given format.

Parameters

object

Procedural style only: A DateTime object returned by date_create()

format

The format of the outputted date string. See the formatting options below. There are also several predefined date constants that may be used instead, so for example DATE_RSS contains the format string 'D, d M Y H:i:s'.

**The following characters are recognized in the `format` parameter string**
`format` character	Description	Example returned values
Day	---	---
`d`	Day of the month, 2 digits with leading zeros	`01` to `31`
`D`	A textual representation of a day, three letters	`Mon` through `Sun`
`j`	Day of the month without leading zeros	`1` to `31`
`l` (lowercase 'L')	A full textual representation of the day of the week	`Sunday` through `Saturday`
`N`	ISO 8601 numeric representation of the day of the week	`1` (for Monday) through `7` (for Sunday)
`S`	English ordinal suffix for the day of the month, 2 characters	`st`, `nd`, `rd` or `th`. Works well with `j`
`w`	Numeric representation of the day of the week	`0` (for Sunday) through `6` (for Saturday)
`z`	The day of the year (starting from 0)	`0` through `365`
Week	---	---
`W`	ISO 8601 week number of year, weeks starting on Monday	Example: `42` (the 42nd week in the year)
Month	---	---
`F`	A full textual representation of a month, such as January or March	`January` through `December`
`m`	Numeric representation of a month, with leading zeros	`01` through `12`
`M`	A short textual representation of a month, three letters	`Jan` through `Dec`
`n`	Numeric representation of a month, without leading zeros	`1` through `12`
`t`	Number of days in the given month	`28` through `31`
Year	---	---
`L`	Whether it's a leap year	`1` if it is a leap year, `0` otherwise.
`o`	ISO 8601 week-numbering year. This has the same value as `Y`, except that if the ISO week number (`W`) belongs to the previous or next year, that year is used instead.	Examples: `1999` or `2003`
`X`	An expanded full numeric representation of a year, at least 4 digits, with `-` for years BCE, and `+` for years CE.	Examples: `-0055`, `+0787`, `+1999`, `+10191`
`x`	An expanded full numeric representation if requried, or a standard full numeral representation if possible (like `Y`). At least four digits. Years BCE are prefixed with a `-`. Years beyond (and including) `10000` are prefixed by a `+`.	Examples: `-0055`, `0787`, `1999`, `+10191`
`Y`	A full numeric representation of a year, at least 4 digits, with `-` for years BCE.	Examples: `-0055`, `0787`, `1999`, `2003`, `10191`
`y`	A two digit representation of a year	Examples: `99` or `03`
Time	---	---
`a`	Lowercase Ante meridiem and Post meridiem	`am` or `pm`
`A`	Uppercase Ante meridiem and Post meridiem	`AM` or `PM`
`B`	Swatch Internet time	`000` through `999`
`g`	12-hour format of an hour without leading zeros	`1` through `12`
`G`	24-hour format of an hour without leading zeros	`0` through `23`
`h`	12-hour format of an hour with leading zeros	`01` through `12`
`H`	24-hour format of an hour with leading zeros	`00` through `23`
`i`	Minutes with leading zeros	`00` to `59`
`s`	Seconds with leading zeros	`00` through `59`
`u`	Microseconds. Note that date() will always generate `000000` since it takes an int parameter, whereas DateTime::format() does support microseconds if DateTime was created with microseconds.	Example: `654321`
`v`	Milliseconds. Same note applies as for `u`.	Example: `654`
Timezone	---	---
`e`	Timezone identifier	Examples: `UTC`, `GMT`, `Atlantic/Azores`
`I` (capital i)	Whether or not the date is in daylight saving time	`1` if Daylight Saving Time, `0` otherwise.
`O`	Difference to Greenwich time (GMT) without colon between hours and minutes	Example: `+0200`
`P`	Difference to Greenwich time (GMT) with colon between hours and minutes	Example: `+02:00`
`p`	The same as `P`, but returns `Z` instead of `+00:00` (available as of PHP 8.0.0)	Examples: `Z` or `+02:00`
`T`	Timezone abbreviation, if known; otherwise the GMT offset.	Examples: `EST`, `MDT`, `+05`
`Z`	Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.	`-43200` through `50400`
Full Date/Time	---	---
`c`	ISO 8601 date	2004-02-12T15:19:21+00:00
`r`	» RFC 2822/» RFC 5322 formatted date	Example: `Thu, 21 Dec 2000 16:01:07 +0200`
`U`	Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)	See also time()

Unrecognized characters in the format string will be printed as-is. The Z format will always return 0 when using gmdate().

Note:
Since this function only accepts int timestamps the u format character is only useful when using the date_format() function with user based timestamps created with date_create().

Return Values

Returns the formatted date string on success.

Changelog

Version	Description
8.2.0	The format characters `X` and `x` have been added.
8.0.0	The format character `p` has been added.

Examples

Example #1 DateTimeInterface::format() example

Object-oriented style


<?php
$date = new DateTimeImmutable('2000-01-01');
echo $date->format('Y-m-d H:i:s');
?>

Procedural style


<?php
$date = date_create('2000-01-01');
echo date_format($date, 'Y-m-d H:i:s');
?>

The above example will output:

2000-01-01 00:00:00

Example #2 More examples


<?php
// set the default timezone to use.
date_default_timezone_set('UTC');

// now
$date = new DateTimeImmutable();

// Prints something like: Wednesday
echo $date->format('l'), "\n";

// Prints something like: Wednesday 19th of October 2022 08:40:48 AM
echo $date->format('l jS \o\f F Y h:i:s A'), "\n";

/* use the constants in the format parameter */
// prints something like: Wed, 19 Oct 2022 08:40:48 +0000
echo $date->format(DateTimeInterface::RFC2822), "\n";
?>

You can prevent a recognized character in the format string from being expanded by escaping it with a preceding backslash. If the character with a backslash is already a special sequence, you may need to also escape the backslash.

Example #3 Escaping characters while formatting


<?php
$date = new DateTimeImmutable();

// prints something like: Wednesday the 19th
echo $date->format('l \t\h\e jS');
?>

To format dates in other languages, IntlDateFormatter::format() can be used instead of DateTimeInterface::format().

Notes

This method does not use locales. All output is in English.

DateTimeInterface::format

DateTimeImmutable::format

DateTime::format

date_format