annotate core/lib/Drupal/Component/Datetime/TimeInterface.php @ 19:fa3358dc1485 tip

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