enh(utility): add timezone generator method to ITimeFactory

developer_manual/digging_deeper/index.rst

@@ -44,3 +44,4 @@ Digging deeper
    deadlock
    phonenumberutil
    out_of_office
+   time

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;