docs: add documentation on date/time formatting to README

Author: ramsey

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

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;