From 36ca38f81784f2becf682b157722e708f453d6c5 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Fri, 1 Jan 2021 22:20:21 -0800
Subject: [PATCH] CRM_Utils_Time - Prefer function names which match the stdlib
 counterparts

There are a large number of calls to `time()`, `date()`, and `strtotime()`
in the codebase.  For someone doing a conversion, it's easier to understand
if the names match.

* Harder conversion
    * `time()` => `CRM_Utils_Time::getTimeRaw()`
    * `date()` => `CRM_Utils_Time::getTime()`
    * `strtotime()` => `strtotime(..., CRM_Utils_Time::getTimeRaw())`
* Easier conversion
    * `time()` => `CRM_Utils_Time::time()`
    * `date()` => `CRM_Utils_Time::date()`
    * `strtotime()` => `CRM_Utils_Time::strtotime()`
---
 CRM/Utils/Time.php | 52 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 2 deletions(-)

diff --git a/CRM/Utils/Time.php b/CRM/Utils/Time.php
index b700e57207..dd56d6b9e4 100644
--- a/CRM/Utils/Time.php
+++ b/CRM/Utils/Time.php
@@ -30,6 +30,50 @@ class CRM_Utils_Time {
    */
   static private $callback = NULL;
 
+  /**
+   * Evaluate a time expression (relative to current time).
+   *
+   * @param string $str
+   *   Ex: '2001-02-03 04:05:06' or '+2 days'
+   * @param string|int $now
+   *   For relative time strings, $now determines the base time.
+   * @return false|int
+   *   The indicated time (seconds since epoch)
+   * @see strtotime()
+   */
+  public static function strtotime($str, $now = 'time()') {
+    if ($now === NULL || $now === 'time()') {
+      $now = self::time();
+    }
+    return strtotime($str, $now);
+  }
+
+  /**
+   * Format a date/time expression.
+   *
+   * @param string $format
+   *   Ex: 'Y-m-d H:i:s'
+   * @param null|int $timestamp
+   *   The time (seconds since epoch). NULL will use current time.
+   * @return string
+   *   Ex: '2001-02-03 04:05:06'
+   * @see date()
+   */
+  public static function date($format, $timestamp = NULL) {
+    return date($format, $timestamp ?: self::time());
+  }
+
+  /**
+   * Get the time.
+   *
+   * @return int
+   *   seconds since epoch
+   * @see time()
+   */
+  public static function time() {
+    return self::$callback === NULL ? time() : call_user_func(self::$callback);
+  }
+
   /**
    * Get the time.
    *
@@ -37,9 +81,11 @@ class CRM_Utils_Time {
    *   Format in which date is to be retrieved.
    *
    * @return string
+   * @deprecated
+   *   Prefer CRM_Utils_Time::date(), whose name looks similar to the stdlib work-a-like.
    */
   public static function getTime($returnFormat = 'YmdHis') {
-    return date($returnFormat, self::getTimeRaw());
+    return date($returnFormat, self::time());
   }
 
   /**
@@ -47,9 +93,11 @@ class CRM_Utils_Time {
    *
    * @return int
    *   seconds since epoch
+   * @deprecated
+   *   Prefer CRM_Utils_Time::time(), whose name looks similar to the stdlib work-a-like.
    */
   public static function getTimeRaw() {
-    return self::$callback === NULL ? time() : call_user_func(self::$callback);
+    return self::time();
   }
 
   /**
-- 
2.25.1