Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Component\Datetime;
Chris@0: 
Chris@0: /**
Chris@0:  * Defines an interface for obtaining system time.
Chris@0:  */
Chris@0: interface TimeInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the timestamp for the current request.
Chris@0:    *
Chris@0:    * This method should be used to obtain the current system time at the start
Chris@0:    * of the request. It will be the same value for the life of the request
Chris@0:    * (even for long execution times).
Chris@0:    *
Chris@0:    * This method can replace instances of
Chris@0:    * @code
Chris@0:    * $request_time = $_SERVER['REQUEST_TIME'];
Chris@0:    * $request_time = REQUEST_TIME;
Chris@0:    * $request_time = $requestStack->getCurrentRequest()->server->get('REQUEST_TIME');
Chris@0:    * $request_time = $request->server->get('REQUEST_TIME');
Chris@0:    * @endcode
Chris@0:    * and most instances of
Chris@0:    * @code
Chris@0:    * $time = time();
Chris@0:    * @endcode
Chris@0:    * with
Chris@0:    * @code
Chris@0:    * $request_time = \Drupal::time()->getRequestTime();
Chris@0:    * @endcode
Chris@0:    * or the equivalent using the injected service.
Chris@0:    *
Chris@0:    * Using the time service, rather than other methods, is especially important
Chris@0:    * when creating tests, which require predictable timestamps.
Chris@0:    *
Chris@0:    * @return int
Chris@0:    *   A Unix timestamp.
Chris@0:    *
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getRequestMicroTime()
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentTime()
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentMicroTime()
Chris@0:    */
Chris@0:   public function getRequestTime();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the timestamp for the current request with microsecond precision.
Chris@0:    *
Chris@0:    * This method should be used to obtain the current system time, with
Chris@0:    * microsecond precision, at the start of the request. It will be the same
Chris@0:    * value for the life of the request (even for long execution times).
Chris@0:    *
Chris@0:    * This method can replace instances of
Chris@0:    * @code
Chris@0:    * $request_time_float = $_SERVER['REQUEST_TIME_FLOAT'];
Chris@0:    * $request_time_float = $requestStack->getCurrentRequest()->server->get('REQUEST_TIME_FLOAT');
Chris@0:    * $request_time_float = $request->server->get('REQUEST_TIME_FLOAT');
Chris@0:    * @endcode
Chris@0:    * and many instances of
Chris@0:    * @code
Chris@0:    * $microtime = microtime();
Chris@0:    * $microtime = microtime(TRUE);
Chris@0:    * @endcode
Chris@0:    * with
Chris@0:    * @code
Chris@0:    * $request_time = \Drupal::time()->getRequestMicroTime();
Chris@0:    * @endcode
Chris@0:    * or the equivalent using the injected service.
Chris@0:    *
Chris@0:    * Using the time service, rather than other methods, is especially important
Chris@0:    * when creating tests, which require predictable timestamps.
Chris@0:    *
Chris@0:    * @return float
Chris@0:    *   A Unix timestamp with a fractional portion.
Chris@0:    *
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getRequestTime()
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentTime()
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentMicroTime()
Chris@0:    */
Chris@0:   public function getRequestMicroTime();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the current system time as an integer.
Chris@0:    *
Chris@0:    * This method should be used to obtain the current system time, at the time
Chris@0:    * the method was called.
Chris@0:    *
Chris@0:    * This method can replace many instances of
Chris@0:    * @code
Chris@0:    * $time = time();
Chris@0:    * @endcode
Chris@0:    * with
Chris@0:    * @code
Chris@0:    * $request_time = \Drupal::time()->getCurrentTime();
Chris@0:    * @endcode
Chris@0:    * or the equivalent using the injected service.
Chris@0:    *
Chris@0:    * This method should only be used when the current system time is actually
Chris@0:    * needed, such as with timers or time interval calculations. If only the
Chris@0:    * time at the start of the request is needed,
Chris@0:    * use TimeInterface::getRequestTime().
Chris@0:    *
Chris@0:    * Using the time service, rather than other methods, is especially important
Chris@0:    * when creating tests, which require predictable timestamps.
Chris@0:    *
Chris@0:    * @return int
Chris@0:    *   A Unix timestamp.
Chris@0:    *
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getRequestTime()
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getRequestMicroTime()
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentMicroTime()
Chris@0:    */
Chris@0:   public function getCurrentTime();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the current system time with microsecond precision.
Chris@0:    *
Chris@0:    * This method should be used to obtain the current system time, with
Chris@0:    * microsecond precision, at the time the method was called.
Chris@0:    *
Chris@0:    * This method can replace many instances of
Chris@0:    * @code
Chris@0:    * $microtime = microtime();
Chris@0:    * $microtime = microtime(TRUE);
Chris@0:    * @endcode
Chris@0:    * with
Chris@0:    * @code
Chris@0:    * $request_time = \Drupal::time()->getCurrentMicroTime();
Chris@0:    * @endcode
Chris@0:    * or the equivalent using the injected service.
Chris@0:    *
Chris@0:    * This method should only be used when the current system time is actually
Chris@0:    * needed, such as with timers or time interval calculations. If only the
Chris@0:    * time at the start of the request and microsecond precision is needed,
Chris@0:    * use TimeInterface::getRequestMicroTime().
Chris@0:    *
Chris@0:    * Using the time service, rather than other methods, is especially important
Chris@0:    * when creating tests, which require predictable timestamps.
Chris@0:    *
Chris@0:    * @return float
Chris@0:    *   A Unix timestamp with a fractional portion.
Chris@0:    *
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getRequestTime()
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getRequestMicroTime()
Chris@0:    * @see \Drupal\Component\Datetime\TimeInterface::getCurrentTime()
Chris@0:    */
Chris@0:   public function getCurrentMicroTime();
Chris@0: 
Chris@0: }