From f76fc77fe7d4d6dfd3a1d0603571a3ea71a748c7 Mon Sep 17 00:00:00 2001
From: Anna Larch <anna@nextcloud.com>
Date: Tue, 5 Mar 2024 13:31:50 +0100
Subject: [PATCH] enh(utility): add timezone generator method to ITimeFactory

Signed-off-by: Anna Larch <anna@nextcloud.com>
---
 developer_manual/digging_deeper/index.rst |  1 +
 developer_manual/digging_deeper/time.rst  | 43 +++++++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 developer_manual/digging_deeper/time.rst

diff --git a/developer_manual/digging_deeper/index.rst b/developer_manual/digging_deeper/index.rst
index 57f4e5e70..437886267 100644
--- a/developer_manual/digging_deeper/index.rst
+++ b/developer_manual/digging_deeper/index.rst
@@ -44,3 +44,4 @@ Digging deeper
    deadlock
    phonenumberutil
    out_of_office
+   time
diff --git a/developer_manual/digging_deeper/time.rst b/developer_manual/digging_deeper/time.rst
new file mode 100644
index 000000000..8f4e53896
--- /dev/null
+++ b/developer_manual/digging_deeper/time.rst
@@ -0,0 +1,43 @@
+=================
+Working with time
+=================
+
+You can inject the ``\OCP\AppFramework\Utility\ITimeFactory`` which wraps commonly used time functions for easier testability.
+
+Methods
+-------
+
+The factory extends the ``\PSR\Clock\ClockInterface`` with the following methods:
+
+.. code-block:: php
+
+    <?php
+
+	/**
+	 * @return int the result of a call to time()
+	 * @since 8.0.0
+	 */
+	public function getTime(): int;
+
+	/**
+	 * @param string $time
+	 * @param \DateTimeZone|null $timezone
+	 * @return \DateTime
+	 * @since 15.0.0
+	 */
+	public function getDateTime(string $time = 'now', \DateTimeZone $timezone = null): \DateTime;
+
+	/**
+	 * @param \DateTimeZone $timezone
+	 * @return static
+	 * @since 26.0.0
+	 */
+	public function withTimeZone(\DateTimeZone $timezone): static;
+
+	/**
+	 * @param string|null $timezone
+	 * @return \DateTimeZone Requested timezone if provided, UTC otherwise
+	 * @throws \Exception
+	 * @since 29.0.0
+	 */
+	public function getTimeZone(?string $timezone = null): \DateTimeZone;