Update to Drupal 8.1.0. For more information, see https://www.drupal.org/drupal-8.1.0-release-notes

core/lib/Drupal/Core/Datetime/DateFormatInterface.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\Core\Datetime\DateFormatInterface.
- */
-
 namespace Drupal\Core\Datetime;
 
 use Drupal\Core\Config\Entity\ConfigEntityInterface;

core/lib/Drupal/Core/Datetime/DateFormatter.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\Core\Datetime\DateFormatter.
- */
-
 namespace Drupal\Core\Datetime;
 
 use Drupal\Core\Config\ConfigFactoryInterface;
@@ -206,10 +201,15 @@ class DateFormatter implements DateFormatterInterface {
       'granularity' => 2,
       'langcode' => NULL,
       'strict' => TRUE,
+      'return_as_object' => FALSE,
     );
 
     if ($options['strict'] && $from > $to) {
-      return $this->t('0 seconds');
+      $string = $this->t('0 seconds');
+      if ($options['return_as_object']) {
+        return new FormattedDateDiff($string, 0);
+      }
+      return $string;
     }
 
     $date_time_from = new \DateTime();
@@ -226,6 +226,7 @@ class DateFormatter implements DateFormatterInterface {
     // We loop over the keys provided by \DateInterval explicitly. Since we
     // don't take the "invert" property into account, the resulting output value
     // will always be positive.
+    $max_age = 1e99;
     foreach (array('y', 'm', 'd', 'h', 'i', 's') as $value) {
       if ($interval->$value > 0) {
         // Switch over the keys to call formatPlural() explicitly with literal
@@ -233,10 +234,12 @@ class DateFormatter implements DateFormatterInterface {
         switch ($value) {
           case 'y':
             $interval_output = $this->formatPlural($interval->y, '1 year', '@count years', array(), array('langcode' => $options['langcode']));
+            $max_age = min($max_age, 365*86400);
             break;
 
           case 'm':
             $interval_output = $this->formatPlural($interval->m, '1 month', '@count months', array(), array('langcode' => $options['langcode']));
+            $max_age = min($max_age, 30*86400);
             break;
 
           case 'd':
@@ -249,10 +252,12 @@ class DateFormatter implements DateFormatterInterface {
               $interval_output .= $this->formatPlural($weeks, '1 week', '@count weeks', array(), array('langcode' => $options['langcode']));
               $days -= $weeks * 7;
               $granularity--;
+              $max_age = min($max_age, 7*86400);
             }
 
             if ((!$output || $weeks > 0) && $granularity > 0 && $days > 0) {
               $interval_output .= ($interval_output ? ' ' : '') . $this->formatPlural($days, '1 day', '@count days', array(), array('langcode' => $options['langcode']));
+              $max_age = min($max_age, 86400);
             }
             else {
               // If we did not output days, set the granularity to 0 so that we
@@ -263,14 +268,17 @@ class DateFormatter implements DateFormatterInterface {
 
           case 'h':
             $interval_output = $this->formatPlural($interval->h, '1 hour', '@count hours', array(), array('langcode' => $options['langcode']));
+            $max_age = min($max_age, 3600);
             break;
 
           case 'i':
             $interval_output = $this->formatPlural($interval->i, '1 minute', '@count minutes', array(), array('langcode' => $options['langcode']));
+            $max_age = min($max_age, 60);
             break;
 
           case 's':
             $interval_output = $this->formatPlural($interval->s, '1 second', '@count seconds', array(), array('langcode' => $options['langcode']));
+            $max_age = min($max_age, 1);
             break;
 
         }
@@ -290,6 +298,11 @@ class DateFormatter implements DateFormatterInterface {
 
     if (empty($output)) {
       $output = $this->t('0 seconds');
+      $max_age = 0;
+    }
+
+    if ($options['return_as_object']) {
+      return new FormattedDateDiff($output, $max_age);
     }
 
     return $output;

core/lib/Drupal/Core/Datetime/DateFormatterInterface.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\Core\Datetime\DateFormatterInterface.
- */
-
 namespace Drupal\Core\Datetime;
 
 /**
@@ -107,8 +102,10 @@ interface DateFormatterInterface {
    *     before the current request time, the result string will be "0 seconds".
    *     If FALSE and $timestamp is before the current request time, the result
    *     string will be the formatted time difference.
+   *   - return_as_object: A Boolean value whether to return a FormattedDateDiff
+   *     object.
    *
-   * @return string
+   * @return string|\Drupal\Core\Datetime\FormattedDateDiff
    *   A translated string representation of the difference between the given
    *   timestamp and the current request time. This interval is always positive.
    *
@@ -135,8 +132,10 @@ interface DateFormatterInterface {
    *     after the current request time, the result string will be "0 seconds".
    *     If FALSE and $timestamp is after the current request time, the result
    *     string will be the formatted time difference.
+   *   - return_as_object: A Boolean value whether to return a FormattedDateDiff
+   *     object.
    *
-   * @return string
+   * @return string|\Drupal\Core\Datetime\FormattedDateDiff
    *   A translated string representation of the difference between the given
    *   timestamp and the current request time. This interval is always positive.
    *
@@ -164,8 +163,10 @@ interface DateFormatterInterface {
    *     can be after the $to timestamp. If TRUE (default) and $from is after
    *     $to, the result string will be "0 seconds". If FALSE and $from is
    *     after $to, the result string will be the formatted time difference.
+   *   - return_as_object: A Boolean value whether to return a FormattedDateDiff
+   *     object.
    *
-   * @return string
+   * @return string|\Drupal\Core\Datetime\FormattedDateDiff
    *   A translated string representation of the interval. This interval is
    *   always positive.
    *

core/lib/Drupal/Core/Datetime/DateHelper.php

@@ -1,7 +1,9 @@
 <?php
+
+namespace Drupal\Core\Datetime;
+
 /**
- * @file
- * Contains \Drupal\Core\Datetime\DateHelper.
+ * Defines Gregorian Calendar date values.
  *
  * Lots of helpful functions for use in massaging dates, specific to the
  * Gregorian calendar system. The values include both translated and
@@ -14,11 +16,6 @@
  * translation should be hard-coded and wrapped in t() so the translation system
  * will be able to process them.
  */
-namespace Drupal\Core\Datetime;
-
-/**
- * Defines Gregorian Calendar date values.
- */
 class DateHelper {
 
   /**

core/lib/Drupal/Core/Datetime/DrupalDateTime.php

@@ -1,9 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\Core\Datetime\DrupalDateTime.
- */
 namespace Drupal\Core\Datetime;
 
 use Drupal\Component\Datetime\DateTimePlus;

core/lib/Drupal/Core/Datetime/Element/DateElementBase.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\Core\Datetime\Element\DateElementBase.
- */
-
 namespace Drupal\Core\Datetime\Element;
 
 use Drupal\Core\Datetime\DrupalDateTime;

core/lib/Drupal/Core/Datetime/Element/Datelist.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\Core\Datetime\Element\Datelist.
- */
-
 namespace Drupal\Core\Datetime\Element;
 
 use Drupal\Component\Utility\NestedArray;

core/lib/Drupal/Core/Datetime/Element/Datetime.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\Core\Datetime\Element\Datetime.
- */
-
 namespace Drupal\Core\Datetime\Element;
 
 use Drupal\Component\Utility\NestedArray;

core/lib/Drupal/Core/Datetime/Entity/DateFormat.php

@@ -1,10 +1,5 @@
 <?php
 
-/**
- * @file
- * Contains \Drupal\Core\Datetime\Entity\DateFormat.
- */
-
 namespace Drupal\Core\Datetime\Entity;
 
 use Drupal\Core\Config\Entity\ConfigEntityBase;

core/lib/Drupal/Core/Datetime/FormattedDateDiff.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace Drupal\Core\Datetime;
+
+use Drupal\Core\Cache\CacheableDependencyInterface;
+use Drupal\Core\Cache\UnchangingCacheableDependencyTrait;
+use Drupal\Core\Render\RenderableInterface;
+
+/**
+ * Contains a formatted time difference.
+ */
+class FormattedDateDiff implements RenderableInterface, CacheableDependencyInterface {
+
+  use UnchangingCacheableDependencyTrait;
+
+  /**
+   * The actual formatted time difference.
+   *
+   * @var string
+   */
+  protected $string;
+
+  /**
+   * The maximum time in seconds that this string may be cached.
+   *
+   * Let's say the time difference is 1 day 1 hour. In this case, we can cache
+   * it until now + 1 hour, so maxAge is 3600 seconds.
+   *
+   * @var int
+   */
+  protected $maxAge;
+
+  /**
+   * Creates a new FormattedDateDiff instance.
+   *
+   * @param string $string
+   *   The formatted time difference.
+   * @param int $max_age
+   *   The maximum time in seconds that this string may be cached.
+   */
+  public function __construct($string, $max_age) {
+    $this->string = $string;
+    $this->maxAge = $max_age;
+  }
+
+  /**
+   * @return string
+   */
+  public function getString() {
+    return $this->string;
+  }
+
+  /**
+   * @return int
+   */
+  public function getMaxAge() {
+    return $this->maxAge;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function toRenderable() {
+    return [
+      '#markup' => $this->string,
+      '#cache' => [
+        'max-age' => $this->maxAge,
+      ],
+    ];
+  }
+
+}

core/lib/Drupal/Core/Datetime/Plugin/Field/FieldWidget/TimestampDatetimeWidget.php

@@ -1,8 +1,4 @@
 <?php
-/**
- * @file
- * Contains \Drupal\Core\Datetime\Plugin\Field\FieldWidget\TimestampDatetimeWidget.
- */
 
 namespace Drupal\Core\Datetime\Plugin\Field\FieldWidget;