From 7960831180fafcd469b9581d613af3b71ea89154 Mon Sep 17 00:00:00 2001
From: Ralf Becker <RalfBecker@outdoor-training.de>
Date: Fri, 22 Jan 2021 15:18:10 +0200
Subject: [PATCH] document EGroupware timestamps and remove own __toString()
 method to be able to compare objects

---
 api/src/DateTime.php              | 20 +++++++++-----------
 api/src/Etemplate/Widget/Date.php |  2 +-
 2 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/api/src/DateTime.php b/api/src/DateTime.php
index d78f2cf64d..5bc0bdec99 100644
--- a/api/src/DateTime.php
+++ b/api/src/DateTime.php
@@ -42,6 +42,13 @@ use DateInterval;
  * The constructor itself throws an \Exception in that case (to be precise it does not handle the one thrown by DateTime constructor).
  * Static methods server2user, user2server and to return NULL, if given time could not be parsed.
  *
+ * Please note: EGroupware historically uses timestamps, which are NOT in UTC!
+ * -----------
+ * So in general the following thre are NOT the same value:
+ * a) (new Api\DateTime($time))->getTimestamp() - regular timestamp in UTC like time()
+ * b) (new Api\DateTime($time))->format('ts')   - EGroupware timestamp in user-timezone, UI and BO objects
+ * c) Api\DateTime($time)::user2server('ts')    - EGroupware timestamp in server-timezone, SO / integer in database
+ *
  * @link http://www.php.net/manual/en/class.datetime.php
  * @link http://www.php.net/manual/en/class.datetimezone.php
  */
@@ -348,7 +355,8 @@ class DateTime extends \DateTime
 			case 'ts':
 				// ToDo: Check if PHP5.3 getTimestamp does the same, or always returns UTC timestamp
 				return mktime(parent::format('H'),parent::format('i'),parent::format('s'),parent::format('m'),parent::format('d'),parent::format('Y'));
-
+			case 'utc':	// alias for "U" / timestamp in UTC
+				return $this->getTimestamp();
 			case 'object':
 			case 'datetime':
 			case 'egw_time':
@@ -382,16 +390,6 @@ class DateTime extends \DateTime
 		return parent::format($type);
 	}
 
-	/**
-	 * Cast object to string
-	 *
-	 * @return string eg. "Wednesday, 2009-11-11 11:11:11 (Europe/Berlin)"
-	 */
-	public function __toString()
-	{
-		return $this->format('l, '.self::DATABASE).' ('.$this->getTimezone()->getName().')';
-	}
-
 	/**
 	 * Convert a server time into a user time
 	 *
diff --git a/api/src/Etemplate/Widget/Date.php b/api/src/Etemplate/Widget/Date.php
index 23b73765c0..c1788148ac 100644
--- a/api/src/Etemplate/Widget/Date.php
+++ b/api/src/Etemplate/Widget/Date.php
@@ -122,7 +122,7 @@ class Date extends Transformer
 		if($date)
 		{
 			// postfix date-string with "Z" so javascript doesn't add/subtract anything
-			$value = $date->format('Y-m-d\TH:i:s\Z');
+			$value = $date->format(Api\DateTime::ET2);
 		}
 		return $value;
 	}