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 }
|