Dates & times¶
Format dates, times, durations, and calendar metadata using the locale's own calendar and conventions. The width argument controls how much detail appears in the formatted result:
width |
date() in en-GB |
time() in en-GB |
|---|---|---|
none |
(omits this part) | (omits this part) |
short |
02/02/2020 |
09:25 |
medium |
2 Feb 2020 |
09:25:30 |
long |
2 February 2020 |
09:25:30 GMT |
full |
Sunday, 2 February 2020 |
09:25:30 Greenwich Mean Time |
What's a moment?
A moment is a single point on the timeline. Accepted values are
a DateTimeInterface, IntlCalendar, Unix seconds, or localtime() array. See Terminology for the distinction
between moments, durations, and ranges.
Date, time, and both¶
moment() formats a date and a time; date() and time() are thin shortcuts
that set the other width to none.
| Method | Parameters | Defaults |
|---|---|---|
moment(value, dateWidth, timeWidth, calendar?) |
both widths + optional calendar | short, short |
date(value, width) |
date width only | short |
time(value, width) |
time width only | short |
$c = new Cosmo('en_GB', ['timeZone' => 'Europe/London']);
$d = new DateTime('2020-02-02 09:25:30');
$c->date($d, 'full'); // "Sunday, 2 February 2020"
$c->time($d, 'short'); // "09:25"
$c->moment($d); // date + time, both 'short'
Calendars¶
The calendar follows the locale automatically — fa_IR renders in the Persian
calendar, th can render Buddhist. Two ways to control it:
- set the
calendarmodifier on the instance ({ calendar: "buddhist" }), or - pass a calendar to
moment()for a one-off.
Pass the special value "gregorian" to force the proleptic Gregorian calendar even
when the locale would imply another:
$fa = new Cosmo('fa_IR');
$fa->date(new DateTime('2020-02-02'), 'long'); // Persian calendar
$fa->moment(new DateTime('2020-02-02'), 'long', 'none', 'gregorian'); // forced
new Cosmo('en', ['calendar' => 'buddhist'])->date($d, 'full');
Duration¶
duration() formats an undirected span — magnitude only, no past/future. For
"3 days ago" you want the directed relative time.
It takes either a scalar number of seconds or a unit breakdown, and a
withWords flag that switches between the digital-clock form and the spelled form:
| Input | withWords |
Result |
|---|---|---|
1222060 (seconds) |
false (default) |
"339:27:40" |
1222060 (seconds) |
true |
"339 hours, 27 minutes, 40 seconds" |
{hours: 3, minutes: 5} |
false |
"3 hr, 5 min" |
{hours: 3, minutes: 5} |
true |
"3 hours, 5 minutes" |
new Cosmo('en')->duration(1222060); // "339:27:40"
new Cosmo('en')->duration(1222060, true); // spelled-out form
new Cosmo('en')->duration(['hours' => 3, 'minutes' => 5]);
The breakdown keys are years, months, weeks, days, hours, minutes,
seconds, milliseconds. Scalar input is always interpreted as
seconds and split into the hours/minutes/seconds clock form.
Time-zone name¶
timeZoneName() returns the localised display name of the instance's timeZone
modifier (falling back to the runtime zone). The style chooses the form:
style |
Example (Australia/Sydney, en) |
|---|---|
long (default) |
Australian Eastern Standard Time |
short |
AEST |
shortOffset |
GMT+10 |
longOffset |
GMT+10:00 |
shortGeneric |
Sydney Time |
longGeneric |
Australian Eastern Time |
$c = new Cosmo('en', ['timeZone' => 'Australia/Sydney']);
$c->timeZoneName(); // "Australian Eastern Standard Time"
$c->timeZoneName('shortOffset'); // "GMT+10" (or +11 during daylight time)
The generic styles drop the standard/daylight distinction (good for labelling a zone in settings); the offset styles reflect the offset at the current instant, so they swing with daylight saving.
Calendar names¶
Localised month and weekday names, aligned to the active calendar. Both take a
width: full (default), long, medium, short.
Weekdays are Sunday-first (ICU symbol order) regardless of the locale's first
day — use weekInfo() to find where the week actually starts.
new Cosmo('en')->monthNames()[0]; // "January"
new Cosmo('en')->weekdayNames('medium'); // ["Sun", "Mon", … "Sat"]
new Cosmo('fa_IR')->monthNames()[0]; // "فروردین" (Persian calendar)
Week information¶
weekInfo() returns the locale's week conventions — the first day of the week and
the minimal-days-in-first-week rule, plus the weekend days:
Days are 1 = Monday … 7 = Sunday.
Arbitrary patterns & ranges¶
Use these methods to format date intervals or specify a custom date pattern:
-
formatMoment(value, pattern)renders a moment with a raw ICU date/time pattern (yyyy-MM-dd,EEEE, d MMM, …) — exact control for filenames, ISO output, or bespoke layouts. -
dateRange(start, end, dateWidth?, timeWidth?)formats an interval, collapsing the shared parts ("Feb 2 – 5, 2020").
new Cosmo('en')->formatMoment($d, 'yyyy-MM-dd'); // "2020-02-02"
new Cosmo('en')->formatMoment($d, 'EEEE, d MMM'); // "Sunday, 2 Feb"
new Cosmo('en')->dateRange($start, $end); // "Feb 2 – 5, 2020" (short/medium)
Common pattern letters: y year · M month (MMM/MMMM for names) · d day ·
E weekday · H/h hour · m minute · s second · a AM/PM · z/Z zone.
Literal text goes in single quotes ('on' d MMM).
Range widths
dateRange() supports short and medium widths only. The interval
skeletons for long and full are not exposed by ext-intl.
Practical examples¶
A sortable log filename, then a friendly header. formatMoment() for the
machine name, the width presets for the human label: