3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
15 * @copyright CiviCRM LLC https://civicrm.org/licensing
21 class CRM_Utils_Time
{
24 * A function which determines the current time.
25 * Only used during testing (with mocked time).
27 * The normal value, NULL, indicates the use of real time.
31 static private $callback = NULL;
34 * Evaluate a time expression (relative to current time).
37 * Ex: '2001-02-03 04:05:06' or '+2 days'
38 * @param string|int $now
39 * For relative time strings, $now determines the base time.
41 * The indicated time (seconds since epoch)
44 public static function strtotime($str, $now = 'time()') {
45 if ($now === NULL ||
$now === 'time()') {
48 return strtotime($str, $now);
52 * Format a date/time expression.
54 * @param string $format
56 * @param null|int $timestamp
57 * The time (seconds since epoch). NULL will use current time.
59 * Ex: '2001-02-03 04:05:06'
62 public static function date($format, $timestamp = NULL) {
63 return date($format, $timestamp ?
: self
::time());
73 public static function time() {
74 return self
::$callback === NULL ?
time() : call_user_func(self
::$callback);
80 * @param string $returnFormat
81 * Format in which date is to be retrieved.
85 * Prefer CRM_Utils_Time::date(), whose name looks similar to the stdlib work-a-like.
87 public static function getTime($returnFormat = 'YmdHis') {
88 return date($returnFormat, self
::time());
97 * Prefer CRM_Utils_Time::time(), whose name looks similar to the stdlib work-a-like.
99 public static function getTimeRaw() {
104 * Set the given time.
106 * @param string $newDateTime
107 * A date formatted with strtotime.
108 * @param string $returnFormat
109 * Format in which date is to be retrieved.
111 * Note: The progression of time will be influenced by TIME_FUNC, which may be:
112 * - 'frozen' (time does not move)
113 * - 'natural' (time moves naturally)
114 * - 'linear:XXX' (time moves in increments of XXX milliseconds - with every lookup)
115 * - 'prng:XXX' (time moves by random increments, between 0 and XXX milliseconds)
118 public static function setTime($newDateTime, $returnFormat = 'YmdHis') {
119 $mode = getenv('TIME_FUNC') ?
getenv('TIME_FUNC') : 'natural';
121 list ($modeName, $modeNum) = explode(":", "$mode:");
125 // Every getTime() will produce the same value (ie $newDateTime).
126 $now = strtotime($newDateTime);
127 self
::$callback = function () use ($now) {
133 // Time changes to $newDateTime and then proceeds naturally.
134 $delta = strtotime($newDateTime) - time();
135 self
::$callback = function () use ($delta) {
136 return time() +
$delta;
141 // Time changes to $newDateTime and then proceeds in fixed increments ($modeNum milliseconds).
142 $incr = ($modeNum / 1000.0);
143 $now = (float) strtotime($newDateTime) - $incr;
144 self
::$callback = function () use (&$now, $incr) {
151 // Time changes to $newDateTime and then proceeds using deterministic pseudorandom increments (of up to $modeNum milliseconds).
152 $seed = md5($newDateTime . chr(0) . $mode, TRUE);
153 $now = (float) strtotime($newDateTime);
154 self
::$callback = function () use (&$seed, &$now, $modeNum) {
155 $mod = gmp_strval(gmp_mod(gmp_import($seed), "$modeNum"));
156 $seed = md5($seed . $now, TRUE);
157 $now = $now +
($mod / 1000.0);
163 throw new \
RuntimeException("Unrecognized TIME_FUNC ($mode)");
166 return self
::getTime($returnFormat);
170 * Remove any time overrides.
172 public static function resetTime() {
173 self
::$callback = NULL;
177 * Approximate time-comparison. $a and $b are considered equal if they
178 * are within $threshold seconds of each other.
181 * Time which can be parsed by strtotime.
183 * Time which can be parsed by strtotime.
184 * @param int $threshold
185 * Maximum allowed difference (in seconds).
188 public static function isEqual($a, $b, $threshold = 0) {
189 $diff = strtotime($b) - strtotime($a);
190 return (abs($diff) <= $threshold);