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