Intl\DateTimeFormatOptions
You can fine-tune date and time formatting with DateTimeFormatOptions
.
use FormatPHP\Config;
use FormatPHP\FormatPHP;
use FormatPHP\Intl;
$config = new Config(new Intl\Locale('es-ES'));
$formatphp = new FormatPHP($config);
$date = new DateTimeImmutable('now');
echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([
'dateStyle' => 'medium',
])); // e.g., "10 jun 2022"
echo $formatphp->formatTime($date, new Intl\DateTimeFormatOptions([
'timeStyle' => 'long',
])); // e.g., "0:58:05 UTC"
General Formatting
DateTimeFormatOptions
accepts the following general options to format dates
and times:
- dateStyle
General formatting of the date, according to the locale. Possible values are: full, long, medium, and short.
echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([ 'dateStyle' => 'full', ])); // e.g., "viernes, 10 de junio de 2022"
- timeStyle
General formatting of the time, according to the locale. Possible values are: full, long, medium, and short.
echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([ 'timeStyle' => 'full', ])); // e.g., "1:10:33 (tiempo universal coordinado)"
Tip
You may use both dateStyle
and timeStyle
together, but if used with
any of the specific formatting options (i.e., weekday
, hour
,
month
, etc.), FormatPHP will throw
FormatPHP\Exception\InvalidArgumentException
.
Specific Formatting
In addition to the general formatting options, the following options provide more specific control over date and time formatting.
echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([
'era' => 'short',
'year' => '2-digit',
'month' => 'short',
'weekday' => 'short',
'day' => 'numeric',
'hour' => '2-digit',
'minute' => '2-digit',
'second' => '2-digit',
])); // e.g., "vie, 10 jun 22 d. C., 1:24:01"
- era
The locale representation of the era (e.g. “AD”, “BC”). Possible values are: long, short, and narrow.
- year
The locale representation of the year. Possible values are: numeric or 2-digit.
- month
The locale representation of the month. Possible values are: numeric, 2-digit, long, short, or narrow.
- weekday
The locale representation of the weekday name. Possible values are: long, short, and narrow.
- day
The locale representation of the day. Possible values are: numeric or 2-digit.
- hour
The locale representation of the hour. Possible values are: numeric or 2-digit.
- minute
The locale representation of the minute. Possible values are: numeric or 2-digit.
- second
The locale representation of the seconds. Possible values are: numeric or 2-digit.
Hint
Not all locales support the same formatting. For example, some locales treat short and narrow eras with the same presentation. Others may treat numeric and 2-digit hours with the same presentation.
These formats are hints for how to display dates and times, according to the given locale. When localizing content, use the locale’s preferred formatting. This is what the underlying ICU library does, and therefore, this what FormatPHP does.
Additional Options
You may use any of the following additional options to further influence date and time formatting.
Hint
While you may use these options with dateStyle
and timeStyle
, the
dateStyle
and timeStyle
general formatting options rigidly stick to
the preferences of the locale, so some of these options might not appear to
have any effect. For example, setting hourCycle
to h23 will not have
any effect when used with timeStyle
in the en-US locale. This is because
en-US prefers h12. Instead, you may use the specific formatting options
with these additional options to achieve the desired results.
- calendar
The calendar system to use. Possible values include: buddhist, chinese, coptic, dangi, ethioaa, ethiopic, gregory, hebrew, indian, islamic, islamic-civil, islamic-rgsa, islamic-tbla, islamic-umalqura, iso8601, japanese, persian, or roc.
echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([ 'dateStyle' => 'full', 'calendar' => 'japanese', ])); // e.g., "Friday, June 10, 4 Reiwa" when locale is en-US
- dayPeriod
The formatting style used for day periods like “in the morning”, “am”, “noon”, “n” etc. Keep in mind not all locales may support presentation of day periods.
Possible values are: narrow, short, or long.
echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([ 'hour' => 'numeric', 'dayPeriod' => 'long', ])); // e.g., "1 at night" when locale is en-US
- hour12
If
true
,hourCycle
will be h12, iffalse
,hourCycle
will be h23. This property overrides any value set byhourCycle
.echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([ 'hour' => '2-digit', 'minute' => '2-digit', 'hour12' => false, ])); // e.g., "13:47"
- hourCycle
The hour cycle to use. Possible values are: h11, h12, h23, and h24.
If specified, this property overrides the
hc
property of the locale’s language tag. Thehour12
property takes precedence over this value.Not all locales support each of these values.
echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([ 'hour' => '2-digit', 'minute' => '2-digit', 'hourCycle' => 'h12', ])); // e.g., "2:06 p. m." when locale is es-ES
- numberingSystem
Specifies a numbering system to use when representing numeric values. You may specify any numbering system defined within Unicode CLDR and bundled in the ICU library version that is available on your platform. However, numbering systems featuring algorithmic numbers do not yet work.
Possible values include (but are not limited to): adlm, ahom, arab, arabext, bali, beng, bhks, brah, cakm, cham, deva, fullwide, gong, gonm, gujr, guru, hanidec, hmng, java, kali, khmr, knda, lana, lanatham, laoo, latn, lepc, limb, mathbold, mathdbl, mathmono, mathsanb, mathsans, mlym, modi, mong, mroo, mtei, mymr, mymrshan, mymrtlng, newa, nkoo, olck, orya, osma, rohg, saur, shrd, sind, sora, sund, takr, talu, tamldec, telu, thai, tibt, tirh, vaii, wara, and wcho.
echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([ 'hour' => '2-digit', 'minute' => '2-digit', 'numberingSystem' => 'jpan', ])); // e.g., "十四:十三"
- timeZoneName
An indicator for how to format the localized representation of the time zone name. Values are: long, short, shortOffset, longOffset, shortGeneric, or longGeneric.
echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([ 'hour' => '2-digit', 'minute' => '2-digit', 'timeZoneName' => 'long', ])); // e.g., "14:17 協定世界時" when the locale is ja-JP
- timeZone
The time zone to use. The default is the system’s default time zone (see date_default_timezone_set()). You may use the zone names of the IANA time zone database, such as “Asia/Shanghai”, “Asia/Kolkata”, “America/New_York”.
echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([ 'hour' => '2-digit', 'minute' => '2-digit', 'timeZone' => 'America/Chicago', 'timeZoneName' => 'long', ])); // e.g., "9:21 AM Central Daylight Time" when the locale is en-US