From 7055bdc2f93c864314fd02a6af1a31704bdc5b25 Mon Sep 17 00:00:00 2001 From: Ben Ramsey Date: Fri, 21 Jan 2022 12:15:35 -0600 Subject: [PATCH] docs: add documentation on date/time formatting to README --- README.md | 97 ++++++++++++++++++++++++++++++ src/Intl/DateTimeFormatOptions.php | 40 ++++++++++++ 2 files changed, 137 insertions(+) diff --git a/README.md b/README.md index a3f7a7b..39770d4 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,103 @@ echo $formatphp->formatMessage([ ]); ``` +### Formatting Dates and Times + +You may use the methods `formatDate()` and `formatTime()` to format dates and +times. + +```php +use FormatPHP\Config; +use FormatPHP\FormatPHP; +use FormatPHP\Intl; + +$config = new Config(new Intl\Locale('es')); +$formatphp = new FormatPHP($config); + +$date = new DateTimeImmutable(); + +echo $formatphp->formatDate($date); // e.g. "21/1/22" +echo $formatphp->formatTime($date); // e.g. "16:58" +``` + +#### Using Intl\DateTimeFormatOptions with formatDate() and formatTime() + +Fine-tune date and time formatting with `Intl\DateTimeFormatOptions`. + +```php +echo $formatphp->formatDate($date, new Intl\DateTimeFormatOptions([ + 'dateStyle' => 'medium', +])); // e.g. "21 ene 2022" +echo $formatphp->formatTime($date, new Intl\DateTimeFormatOptions([ + 'timeStyle' => 'long', +])); // e.g. "16:58:31 UTC" +``` + +`DateTimeFormatOptions` accepts the following general options for formatting +dates and times: + +* `dateStyle`: General formatting of the date, according to the locale. Possible + values include: `full`, `long`, `medium`, and `short`. +* `timeStyle`: General formatting of the time, according to the locale. Possible + values include: `full`, `long`, `medium`, and `short`. + +> ℹ️ **Note:** `dateStyle` and `timeStyle` may be used together, but they cannot +> be used with more granular formatting options (i.e., `era`, `year`, `month`, +> `day`, `weekday`, `day`, `hour`, `minute`, or `second`). + +Instead of `dateStyle` and `timeStyle`, you may use the following options for +more granular formatting of dates and times: + +* `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`. + +Additional options include: + +* `calendar`: The calendar system to use. Possible values include: `buddhist`, + `chinese`, `coptic`, `dangi`, `ethioaa`, `ethiopia`, `ethiopic`, `gregory`, + `hebrew`, `indian`, `islamic`, `islamic-civil`, `islamic-rgsa`, `islamic-tbla`, + `islamic-umalqura`, `iso8601`, `japanese`, `persian`, or `roc`. +* `dayPeriod`: The formatting style used for day periods like "in the morning", + "am", "noon", "n" etc. Values include: `narrow`, `short`, or `long`. +* `fractionalSecondDigits`: The number of digits used to represent fractions of + a second (any additional digits are truncated). Values may be: `0`, `1`, `2`, + or `3`. +* `hour12`: If `true`, `hourCycle` will be `h12`, if `false`, `hourCycle` will + be `h23`. This property overrides any value set by `hourCycle`. +* `hourCycle`: The hour cycle to use. Values include: `h11`, `h12`, `h23`, and + `h24`. If specified, this property overrides the `hc` property of the locale's + language tag. The `hour12` property takes precedence over this value. +* `numberingSystem`: The numeral system to use. Possible values include: `arab`, + `arabext`, `armn`, `armnlow`, `bali`, `beng`, `brah`, `cakm`, `cham`, `deva`, + `diak`, `ethi`, `finance`, `fullwide`, `geor`, `gong`, `gonm`, `grek`, `greklow`, + `gujr`, `guru`, `hanidays`, `hanidec`, `hans`, `hansfin`, `hant`, `hantfin`, + `hebr`, `hmnp`, `java`, `jpan`, `jpanfin`, `jpanyear`, `kali`, `khmr`, `knda`, + `lana`, `lanatham`, `laoo`, `lepc`, `limb`, `mlym`, `mong`, `mtei`, `mymr`, + `mymrshan`, `native`, `nkoo`, `olck`, `orya`, `osma`, `rohg`, `roman`, `romanlow`, + `saur`, `shrd`, `sora`, `sund`, `takr`, `talu`, `taml`, `tamldec`, `telu`, + `thai`, `tibt`, `tnsa`, `traditional`, `vaii`, or `wcho`. +* `timeZoneName`: An indicator for how to format the localized representation of + the time zone name. Values include: `long`, `short`, `shortOffset`, `longOffset`, + `shortGeneric`, or `longGeneric`. +* `timeZone`: The time zone to use. The default is the system's default time zone + (see [date_default_timezone_set()](https://www.php.net/date_default_timezone_set)). + You may use the zone names of the [IANA time zone database](https://www.iana.org/time-zones), + such as "Asia/Shanghai", "Asia/Kolkata", "America/New_York". + ### Rich Text Formatting (Use of Tags in Messages) While the ICU message syntax does not prohibit the use of HTML tags in formatted diff --git a/src/Intl/DateTimeFormatOptions.php b/src/Intl/DateTimeFormatOptions.php index b4b8630..88baaf4 100644 --- a/src/Intl/DateTimeFormatOptions.php +++ b/src/Intl/DateTimeFormatOptions.php @@ -91,16 +91,23 @@ class DateTimeFormatOptions implements JsonSerializable public ?string $timeStyle = null; /** + * The calendar system to use + * * @var CalendarType | null */ public ?string $calendar = null; /** + * The formatting style used for day periods like "in the morning", "am", + * "noon", "n" etc. + * * @var PeriodType | null */ public ?string $dayPeriod = null; /** + * The numeral system to use + * * @var NumeralType | null */ public ?string $numberingSystem = null; @@ -117,59 +124,92 @@ class DateTimeFormatOptions implements JsonSerializable */ public ?string $timeZone = null; + /** + * If true, hourCycle will be "h12," if false, hourCycle will be "h23" + * + * This property overrides any value set by hourCycle. + */ public ?bool $hour12 = null; /** + * The hour cycle to use + * + * If this property is specified, it overrides the hc property of the + * language tag, if set. The hour12 property takes precedence over + * this value. + * * @var HourType | null */ public ?string $hourCycle = null; /** + * The locale representation of the weekday name. + * * @var PeriodType | null */ public ?string $weekday = null; /** + * The locale representation of the era (e.g. "AD", "BC") + * * @var PeriodType | null */ public ?string $era = null; /** + * The locale representation of the year + * * @var WidthType | null */ public ?string $year = null; /** + * The locale representation of the month + * * @var WidthType | PeriodType | null */ public ?string $month = null; /** + * The locale representation of the day + * * @var WidthType | null */ public ?string $day = null; /** + * The locale representation of the hour + * * @var WidthType | null */ public ?string $hour = null; /** + * The locale representation of the minute + * * @var WidthType | null */ public ?string $minute = null; /** + * The locale representation of the seconds + * * @var WidthType | null */ public ?string $second = null; /** + * The number of digits used to represent fractions of a second (any + * additional digits are truncated) + * * @var FractionDigitsType | null */ public ?int $fractionalSecondDigits = null; /** + * An indicator for how to format the localized representation of the time + * zone name + * * @var TimeZoneNameType | null */ public ?string $timeZoneName = null;