Carbon::format
Formats a date using PHP's date() format characters.
public function format(string $format): string- Added in Laravel Carbon 1.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$$format | string | A PHP date() format string. Letters are format characters; escape any literal letter with a backslash. Carbon routes the call through its configured format function, which is what makes localized output possible. |
Return value
stringThe date rendered with the given format characters, in the instance's own timezone.
Changelog
- PHP 2.0isoFormat() was added for locale-aware tokens (dddd, MMMM) as a companion to format(), whose characters are never translated.
format() renders a Carbon instance as a string using PHP's date() characters — Y for a four-digit year, m for a zero-padded month, H:i:s for the time. Every letter is a token, so any literal letter must be escaped with a backslash: 'l \a\t g:ia', not 'l at g:ia', or the a and t expand into am/pm and a timezone abbreviation.
format is not localized
Month and day names from format() are always English, whatever the app locale. For a translated date use isoFormat(), which takes different tokens — dddd D MMMM YYYY rather than l j F Y — and honours the instance locale. Mixing the two token vocabularies is a common source of odd output.
It renders the instance's timezone
A Carbon instance carries a timezone, and format() shows that wall clock. Two instances of the same instant in different zones format differently. Call setTimezone() — or Laravel's ->timezone($tz) — before formatting rather than adjusting the output afterwards.
For common shapes prefer the named helpers: toDateString(), toDateTimeString(), toIso8601String(). Note that toDateTimeString() drops microseconds.
Example
When to use it
- Rendering a stored timestamp in a view in a fixed presentation format.
- Producing a filename or export column with a sortable Y-m-d prefix.
- Emitting a specific layout required by a third-party API or CSV import.
Frequently asked questions
Why are my month names always in English?
format() uses PHP's date() characters, which are never translated. Use isoFormat() with its own tokens — isoFormat('dddd D MMMM YYYY') — together with ->locale('es') for a translated rendering.
How do I include a literal letter in a format string?
Escape it with a backslash: 'l \a\t g:ia' renders 'Saturday at 6:05pm', while an unescaped 'at' expands into am/pm and a timezone abbreviation. In a double-quoted PHP string the backslashes themselves need doubling.
Why does toDateTimeString() lose my microseconds?
It formats as 'Y-m-d H:i:s', which has no sub-second component. Call format('Y-m-d H:i:s.u') or toIso8601String() with microsecond precision when the fraction matters, for example when comparing an end-of-day boundary.
More examples
Formatting for display versus for machines
toDateTimeString() truncates the microseconds, which is why a value round-tripped through it can compare as earlier than the original. Reach for the explicit .u format when sub-second precision has to survive.
<?php
use Carbon\Carbon;
$date = Carbon::parse('2026-03-14 18:05:09.123456', 'UTC');
echo $date->toDateString(), "\n"; // 2026-03-14
echo $date->toDateTimeString(), "\n"; // 2026-03-14 18:05:09 (microseconds dropped)
echo $date->toIso8601String(), "\n"; // 2026-03-14T18:05:09+00:00
echo $date->format('Y-m-d H:i:s.u'), "\n"; // 2026-03-14 18:05:09.123456
echo $date->format('U'), "\n"; // 1773511509Localized output needs isoFormat
The same instance renders in English through format() and in Spanish through isoFormat(), because only the latter consults the locale. The LLLL token is a locale-defined preset, so it also reorders the parts the way that language writes dates.
<?php
use Carbon\Carbon;
$date = Carbon::parse('2026-03-14 18:05:09');
echo $date->locale('es')->format('l j F Y'), "\n";
// Saturday 14 March 2026 <- format() is never translated
echo $date->locale('es')->isoFormat('dddd D MMMM YYYY'), "\n";
// sábado 14 marzo 2026
echo $date->locale('es')->isoFormat('LLLL'), "\n";
// sábado, 14 de marzo de 2026 18:05Formatting in the reader's timezone
format() always prints the instance's own wall clock, so the timezone has to be changed before formatting, not after. copy() keeps the original UTC instance intact for any other use in the same request.
<?php
use Carbon\Carbon;
$utc = Carbon::parse('2026-03-14 18:05:09', 'UTC');
echo $utc->format('Y-m-d H:i T'), "\n";
// 2026-03-14 18:05 UTC
echo $utc->copy()->setTimezone('America/New_York')->format('Y-m-d H:i T'), "\n";
// 2026-03-14 14:05 EDT
Discussion