updated formatter docs and allow using DateTimeImmutable

framework/i18n/Formatter.php

@@ -7,7 +7,9 @@
 
 namespace yii\i18n;
 
+use DateInterval;
 use DateTime;
+use DateTimeInterface;
 use DateTimeZone;
 use IntlDateFormatter;
 use NumberFormatter;
@@ -566,7 +568,7 @@ class Formatter extends Component
      */
     protected function normalizeDatetimeValue($value)
     {
-        if ($value === null || $value instanceof DateTime) {
+        if ($value === null || $value instanceof DateTime || $value instanceof DateTimeInterface) {
             // skip any processing
             return $value;
         }
@@ -595,13 +597,13 @@ class Formatter extends Component
 
     /**
      * Formats a date, time or datetime in a float number as UNIX timestamp (seconds since 01-01-1970).
-     * @param integer|string|DateTime|\DateInterval $value the value to be formatted. The following
+     * @param integer|string|DateTime $value the value to be formatted. The following
      * types of value are supported:
      *
      * - an integer representing a UNIX timestamp
-     * - a string that can be parsed into a UNIX timestamp via `strtotime()` or that can be passed to a DateInterval constructor.
-     * - a PHP DateTime object
-     * - a PHP DateInterval object (a positive time interval will refer to the past, a negative one to the future)
+     * - a string that can be [parsed to create a DateTime object](http://php.net/manual/en/datetime.formats.php).
+     *   The timestamp is assumed to be in UTC unless a timezone is explicitly given.
+     * - a PHP [DateTime](http://php.net/manual/en/class.datetime.php) object
      *
      * @return string the formatted result.
      */
@@ -617,15 +619,23 @@ class Formatter extends Component
     /**
      * Formats the value as the time interval between a date and now in human readable form.
      *
-     * @param integer|string|DateTime|\DateInterval $value the value to be formatted. The following
+     * This method can be used in three different ways:
+     *
+     * 1. Using a timestamp that is relative to `now`.
+     * 2. Using a timestamp that is relative to the `$referenceTime`.
+     * 3. Using a `DateInterval` object.
+     *
+     * @param integer|string|DateTime|DateInterval $value the value to be formatted. The following
      * types of value are supported:
      *
      * - an integer representing a UNIX timestamp
-     * - a string that can be parsed into a UNIX timestamp via `strtotime()` or that can be passed to a DateInterval constructor.
-     * - a PHP DateTime object
+     * - a string that can be [parsed to create a DateTime object](http://php.net/manual/en/datetime.formats.php).
+     *   The timestamp is assumed to be in UTC unless a timezone is explicitly given.
+     * - a PHP [DateTime](http://php.net/manual/en/class.datetime.php) object
      * - a PHP DateInterval object (a positive time interval will refer to the past, a negative one to the future)
      *
-     * @param integer|string|DateTime|\DateInterval $referenceTime if specified the value is used instead of `now`.
+     * @param integer|string|DateTime $referenceTime if specified the value is used as a reference time instead of `now`
+     * when `$value` is not a `DateInterval` object.
      * @return string the formatted result.
      * @throws InvalidParamException if the input value can not be evaluated as a date value.
      */
@@ -635,7 +645,7 @@ class Formatter extends Component
             return $this->nullDisplay;
         }
 
-        if ($value instanceof \DateInterval) {
+        if ($value instanceof DateInterval) {
             $interval = $value;
         } else {
             $timestamp = $this->normalizeDatetimeValue($value);
@@ -644,7 +654,7 @@ class Formatter extends Component
                 // $value is not a valid date/time value, so we try
                 // to create a DateInterval with it
                 try {
-                    $interval = new \DateInterval($value);
+                    $interval = new DateInterval($value);
                 } catch (\Exception $e) {
                     // invalid date/time and invalid interval
                     return $this->nullDisplay;