www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Component/Datetime/TimeInterface.php

   1 <?php
   2
   3 namespace Drupal\Component\Datetime;
   4
   5 /**
   6  * Defines an interface for obtaining system time.
   7  */
   8 interface TimeInterface {
   9
  10   /**
  11    * Returns the timestamp for the current request.
  12    *
  13    * This method should be used to obtain the current system time at the start
  14    * of the request. It will be the same value for the life of the request
  15    * (even for long execution times).
  16    *
  17    * This method can replace instances of
  18    * @code
  19    * $request_time = $_SERVER['REQUEST_TIME'];
  20    * $request_time = REQUEST_TIME;
  21    * $request_time = $requestStack->getCurrentRequest()->server->get('REQUEST_TIME');
  22    * $request_time = $request->server->get('REQUEST_TIME');
  23    * @endcode
  24    * and most instances of
  25    * @code
  26    * $time = time();
  27    * @endcode
  28    * with
  29    * @code
  30    * $request_time = \Drupal::time()->getRequestTime();
  31    * @endcode
  32    * or the equivalent using the injected service.
  33    *
  34    * Using the time service, rather than other methods, is especially important
  35    * when creating tests, which require predictable timestamps.
  36    *
  37    * @return int
  38    *   A Unix timestamp.
  39    *
  40    * @see \Drupal\Component\Datetime\TimeInterface::getRequestMicroTime()
  41    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentTime()
  42    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentMicroTime()
  43    */
  44   public function getRequestTime();
  45
  46   /**
  47    * Returns the timestamp for the current request with microsecond precision.
  48    *
  49    * This method should be used to obtain the current system time, with
  50    * microsecond precision, at the start of the request. It will be the same
  51    * value for the life of the request (even for long execution times).
  52    *
  53    * This method can replace instances of
  54    * @code
  55    * $request_time_float = $_SERVER['REQUEST_TIME_FLOAT'];
  56    * $request_time_float = $requestStack->getCurrentRequest()->server->get('REQUEST_TIME_FLOAT');
  57    * $request_time_float = $request->server->get('REQUEST_TIME_FLOAT');
  58    * @endcode
  59    * and many instances of
  60    * @code
  61    * $microtime = microtime();
  62    * $microtime = microtime(TRUE);
  63    * @endcode
  64    * with
  65    * @code
  66    * $request_time = \Drupal::time()->getRequestMicroTime();
  67    * @endcode
  68    * or the equivalent using the injected service.
  69    *
  70    * Using the time service, rather than other methods, is especially important
  71    * when creating tests, which require predictable timestamps.
  72    *
  73    * @return float
  74    *   A Unix timestamp with a fractional portion.
  75    *
  76    * @see \Drupal\Component\Datetime\TimeInterface::getRequestTime()
  77    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentTime()
  78    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentMicroTime()
  79    */
  80   public function getRequestMicroTime();
  81
  82   /**
  83    * Returns the current system time as an integer.
  84    *
  85    * This method should be used to obtain the current system time, at the time
  86    * the method was called.
  87    *
  88    * This method can replace many instances of
  89    * @code
  90    * $time = time();
  91    * @endcode
  92    * with
  93    * @code
  94    * $request_time = \Drupal::time()->getCurrentTime();
  95    * @endcode
  96    * or the equivalent using the injected service.
  97    *
  98    * This method should only be used when the current system time is actually
  99    * needed, such as with timers or time interval calculations. If only the
 100    * time at the start of the request is needed,
 101    * use TimeInterface::getRequestTime().
 102    *
 103    * Using the time service, rather than other methods, is especially important
 104    * when creating tests, which require predictable timestamps.
 105    *
 106    * @return int
 107    *   A Unix timestamp.
 108    *
 109    * @see \Drupal\Component\Datetime\TimeInterface::getRequestTime()
 110    * @see \Drupal\Component\Datetime\TimeInterface::getRequestMicroTime()
 111    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentMicroTime()
 112    */
 113   public function getCurrentTime();
 114
 115   /**
 116    * Returns the current system time with microsecond precision.
 117    *
 118    * This method should be used to obtain the current system time, with
 119    * microsecond precision, at the time the method was called.
 120    *
 121    * This method can replace many instances of
 122    * @code
 123    * $microtime = microtime();
 124    * $microtime = microtime(TRUE);
 125    * @endcode
 126    * with
 127    * @code
 128    * $request_time = \Drupal::time()->getCurrentMicroTime();
 129    * @endcode
 130    * or the equivalent using the injected service.
 131    *
 132    * This method should only be used when the current system time is actually
 133    * needed, such as with timers or time interval calculations. If only the
 134    * time at the start of the request and microsecond precision is needed,
 135    * use TimeInterface::getRequestMicroTime().
 136    *
 137    * Using the time service, rather than other methods, is especially important
 138    * when creating tests, which require predictable timestamps.
 139    *
 140    * @return float
 141    *   A Unix timestamp with a fractional portion.
 142    *
 143    * @see \Drupal\Component\Datetime\TimeInterface::getRequestTime()
 144    * @see \Drupal\Component\Datetime\TimeInterface::getRequestMicroTime()
 145    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentTime()
 146    */
 147   public function getCurrentMicroTime();
 148
 149 }