Skip to content

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 calendar modifier 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:

new Cosmo('en_US')->weekInfo(); // ['firstDay' => 7, 'weekend' => [6, 7], 'minimalDays' => 1]

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:

$c = new Cosmo('en_GB', ['timeZone' => 'UTC']);
$name   = $c->formatMoment($d, "yyyy-MM-dd'T'HH-mm-ss") . '.log'; // 2020-02-02T09-25-30.log
$header = $c->moment($d, 'full', 'short');                        // "Sunday, 2 February 2020 at 09:25"