From 8904ae27cbc9e942b8c0476fe6a5ee9a9785a78d Mon Sep 17 00:00:00 2001
From: mjansen <mjansen@databay.de>
Date: Sat, 5 Feb 2022 12:16:56 +0100
Subject: [PATCH] Clock: Introduce `PSR-20 Clock Service`

---
 src/DI/Container.php                |  9 ++--
 src/Data/Clock/ClockFactory.php     | 28 ++++++++++++
 src/Data/Clock/ClockFactoryImpl.php | 46 +++++++++++++++++++
 src/Data/Clock/ClockInterface.php   | 24 ++++++++++
 src/Data/Clock/LocalClock.php       | 35 +++++++++++++++
 src/Data/Clock/SystemClock.php      | 27 ++++++++++++
 src/Data/Clock/UtcClock.php         | 28 ++++++++++++
 src/Data/Factory.php                |  8 ++++
 src/Data/README.md                  | 68 +++++++++++++++++++++++++++++
 src/Data/ROADMAP.md                 |  1 +
 tests/Data/LocalClockTest.php       | 45 +++++++++++++++++++
 tests/Data/SystemClockTest.php      | 44 +++++++++++++++++++
 tests/Data/UtcClockTest.php         | 43 ++++++++++++++++++
 13 files changed, 400 insertions(+), 6 deletions(-)
 create mode 100644 src/Data/Clock/ClockFactory.php
 create mode 100644 src/Data/Clock/ClockFactoryImpl.php
 create mode 100644 src/Data/Clock/ClockInterface.php
 create mode 100644 src/Data/Clock/LocalClock.php
 create mode 100644 src/Data/Clock/SystemClock.php
 create mode 100644 src/Data/Clock/UtcClock.php
 create mode 100644 src/Data/ROADMAP.md
 create mode 100644 tests/Data/LocalClockTest.php
 create mode 100644 tests/Data/SystemClockTest.php
 create mode 100644 tests/Data/UtcClockTest.php

diff --git a/src/DI/Container.php b/src/DI/Container.php
index ddf6d6c0e835..ab45f3043c36 100644
--- a/src/DI/Container.php
+++ b/src/DI/Container.php
@@ -3,13 +3,10 @@
 
 namespace ILIAS\DI;
 
-use ILIAS\Filesystem\Filesystems;
-use ILIAS\FileUpload\FileUpload;
-use ILIAS\GlobalScreen\Services;
-use ILIAS\Refinery\Factory;
-use ILIAS\Skill\Service\SkillService;
-use ILIAS\Repository;
 use ILIAS\BackgroundTasks\BackgroundTaskServices;
+use ILIAS\Data\Clock\ClockFactoryImpl;
+use ILIAS\Repository;
+use ILIAS\Skill\Service\SkillService;
 
 /******************************************************************************
  *
diff --git a/src/Data/Clock/ClockFactory.php b/src/Data/Clock/ClockFactory.php
new file mode 100644
index 000000000000..0f773169c0dd
--- /dev/null
+++ b/src/Data/Clock/ClockFactory.php
@@ -0,0 +1,28 @@
+<?php declare(strict_types=1);
+
+/******************************************************************************
+ *
+ * This file is part of ILIAS, a powerful learning management system.
+ *
+ * ILIAS is licensed with the GPL-3.0, you should have received a copy
+ * of said license along with the source code.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ *      https://www.ilias.de
+ *      https://github.com/ILIAS-eLearning
+ *
+ *****************************************************************************/
+
+namespace ILIAS\Data\Clock;
+
+use DateTimeZone;
+
+interface ClockFactory
+{
+    public function system() : ClockInterface;
+
+    public function utc() : ClockInterface;
+
+    public function local(DateTimeZone $time_zone) : ClockInterface;
+}
diff --git a/src/Data/Clock/ClockFactoryImpl.php b/src/Data/Clock/ClockFactoryImpl.php
new file mode 100644
index 000000000000..169ebe627517
--- /dev/null
+++ b/src/Data/Clock/ClockFactoryImpl.php
@@ -0,0 +1,46 @@
+<?php declare(strict_types=1);
+
+/******************************************************************************
+ *
+ * This file is part of ILIAS, a powerful learning management system.
+ *
+ * ILIAS is licensed with the GPL-3.0, you should have received a copy
+ * of said license along with the source code.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ *      https://www.ilias.de
+ *      https://github.com/ILIAS-eLearning
+ *
+ *****************************************************************************/
+
+namespace ILIAS\Data\Clock;
+
+use DateTimeZone;
+
+class ClockFactoryImpl implements ClockFactory
+{
+    /**
+     * @inheritDoc
+     */
+    public function system() : ClockInterface
+    {
+        return new SystemClock();
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function utc() : ClockInterface
+    {
+        return new UtcClock();
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function local(DateTimeZone $time_zone) : ClockInterface
+    {
+        return new LocalClock($time_zone);
+    }
+}
diff --git a/src/Data/Clock/ClockInterface.php b/src/Data/Clock/ClockInterface.php
new file mode 100644
index 000000000000..2115d56b076c
--- /dev/null
+++ b/src/Data/Clock/ClockInterface.php
@@ -0,0 +1,24 @@
+<?php declare(strict_types=1);
+
+/******************************************************************************
+ *
+ * This file is part of ILIAS, a powerful learning management system.
+ *
+ * ILIAS is licensed with the GPL-3.0, you should have received a copy
+ * of said license along with the source code.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ *      https://www.ilias.de
+ *      https://github.com/ILIAS-eLearning
+ *
+ *****************************************************************************/
+
+namespace ILIAS\Data\Clock;
+
+use DateTimeImmutable;
+
+interface ClockInterface
+{
+    public function now() : DateTimeImmutable;
+}
diff --git a/src/Data/Clock/LocalClock.php b/src/Data/Clock/LocalClock.php
new file mode 100644
index 000000000000..ae0d8dc1aeca
--- /dev/null
+++ b/src/Data/Clock/LocalClock.php
@@ -0,0 +1,35 @@
+<?php declare(strict_types=1);
+
+/******************************************************************************
+ *
+ * This file is part of ILIAS, a powerful learning management system.
+ *
+ * ILIAS is licensed with the GPL-3.0, you should have received a copy
+ * of said license along with the source code.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ *      https://www.ilias.de
+ *      https://github.com/ILIAS-eLearning
+ *
+ *****************************************************************************/
+
+namespace ILIAS\Data\Clock;
+
+use DateTimeImmutable;
+use DateTimeZone;
+
+class LocalClock implements ClockInterface
+{
+    private DateTimeZone $time_zone;
+
+    public function __construct(DateTimeZone $time_zone)
+    {
+        $this->time_zone = $time_zone;
+    }
+
+    public function now() : DateTimeImmutable
+    {
+        return new DateTimeImmutable('now', $this->time_zone);
+    }
+}
diff --git a/src/Data/Clock/SystemClock.php b/src/Data/Clock/SystemClock.php
new file mode 100644
index 000000000000..0f2d37fe59d8
--- /dev/null
+++ b/src/Data/Clock/SystemClock.php
@@ -0,0 +1,27 @@
+<?php declare(strict_types=1);
+
+/******************************************************************************
+ *
+ * This file is part of ILIAS, a powerful learning management system.
+ *
+ * ILIAS is licensed with the GPL-3.0, you should have received a copy
+ * of said license along with the source code.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ *      https://www.ilias.de
+ *      https://github.com/ILIAS-eLearning
+ *
+ *****************************************************************************/
+
+namespace ILIAS\Data\Clock;
+
+use DateTimeImmutable;
+
+class SystemClock implements ClockInterface
+{
+    public function now() : DateTimeImmutable
+    {
+        return new DateTimeImmutable('now');
+    }
+}
diff --git a/src/Data/Clock/UtcClock.php b/src/Data/Clock/UtcClock.php
new file mode 100644
index 000000000000..5b08ca0ff782
--- /dev/null
+++ b/src/Data/Clock/UtcClock.php
@@ -0,0 +1,28 @@
+<?php declare(strict_types=1);
+
+/******************************************************************************
+ *
+ * This file is part of ILIAS, a powerful learning management system.
+ *
+ * ILIAS is licensed with the GPL-3.0, you should have received a copy
+ * of said license along with the source code.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ *      https://www.ilias.de
+ *      https://github.com/ILIAS-eLearning
+ *
+ *****************************************************************************/
+
+namespace ILIAS\Data\Clock;
+
+use DateTimeImmutable;
+use DateTimeZone;
+
+class UtcClock implements ClockInterface
+{
+    public function now() : DateTimeImmutable
+    {
+        return new DateTimeImmutable('now', new DateTimeZone('UTC'));
+    }
+}
diff --git a/src/Data/Factory.php b/src/Data/Factory.php
index 9b8a430cb1e9..f93346da9c20 100644
--- a/src/Data/Factory.php
+++ b/src/Data/Factory.php
@@ -4,6 +4,9 @@
 
 namespace ILIAS\Data;
 
+use ILIAS\Data\Clock\ClockFactory;
+use ILIAS\Data\Clock\ClockFactoryImpl;
+
 /**
  * Builds data types.
  *
@@ -154,4 +157,9 @@ public function link(string $label, URI $url) : Link
     {
         return new Link($label, $url);
     }
+
+    public function clock() : ClockFactory
+    {
+        return new ClockFactoryImpl();
+    }
 }
diff --git a/src/Data/README.md b/src/Data/README.md
index fb8d2bf27628..65c7afc0af7b 100644
--- a/src/Data/README.md
+++ b/src/Data/README.md
@@ -3,6 +3,26 @@
 This service should contain standard datatypes for ILIAS that are used in many
 locations in the system and do not belong to a certain service.
 
+The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
+“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
+interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+**Table of Contents**
+* [Result](#result)
+* [Color](#color)
+* [URI](#uri)
+* [DataSize](#datasize)
+* [Password](#password)
+* [ClientId](#clientid)
+* [ReferenceId](#referenceid)
+* [ObjectId](#objectid)
+* [Alphanumeric](#alphanumeric)
+* [PositiveInteger](#positiveinteger)
+* [DateFormat](#dateformat)
+* [Range](#Range)
+* [Order](#order)
+* [Clock](#clock)
+
 Other examples for data types that could (and maybe should) be added here:
 
 * Option (akin to rusts type)
@@ -387,3 +407,51 @@ assert($order2->get() === ['subject1' => 'ASC', 'subject2' => 'DESC']);
 assert($join === 'sort subject1 ASC, subject2 DESC,');
 ?>
 ```
+
+## Clock
+
+This package provides a fully psr-20 compliant clock handling.
+
+### Example
+
+#### System Clock
+
+The `\ILIAS\Data\Clock\SystemClock` returns a `\DateTimeImmutable` instance always referring to the
+current default system timezone.
+
+```php
+<?php
+$f = new \ILIAS\Data\Factory;
+
+$clock = $f->clock()->system();
+$now = $clock->now();
+?>
+```
+
+#### UTC Clock
+
+The `\ILIAS\Data\Clock\UtcClock` returns a `\DateTimeImmutable` instance always referring to the
+`UTC` timezone.
+
+```php
+<?php
+$f = new \ILIAS\Data\Factory;
+
+$clock = $f->clock()->utc();
+$now = $clock->now();
+?>
+```
+
+#### Local Clock
+
+The `\ILIAS\Data\Clock\UtcClock` returns a `\DateTimeImmutable` instance always referring to the
+timezone passed to the factory method.
+
+```php
+<?php
+$f = new \ILIAS\Data\Factory;
+
+$clock = $f->clock()->local(new \DateTimeZone('Europe/Berlin'));
+$now = $clock->now();
+?>
+```
\ No newline at end of file
diff --git a/src/Data/ROADMAP.md b/src/Data/ROADMAP.md
new file mode 100644
index 000000000000..437766dd8f3d
--- /dev/null
+++ b/src/Data/ROADMAP.md
@@ -0,0 +1 @@
+# Roadmap
diff --git a/tests/Data/LocalClockTest.php b/tests/Data/LocalClockTest.php
new file mode 100644
index 000000000000..bac69a015c02
--- /dev/null
+++ b/tests/Data/LocalClockTest.php
@@ -0,0 +1,45 @@
+<?php declare(strict_types=1);
+
+/******************************************************************************
+ *
+ * This file is part of ILIAS, a powerful learning management system.
+ *
+ * ILIAS is licensed with the GPL-3.0, you should have received a copy
+ * of said license along with the source code.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ *      https://www.ilias.de
+ *      https://github.com/ILIAS-eLearning
+ *
+ *****************************************************************************/
+
+namespace ILIAS\Data\Clock;
+
+use DateTimeZone;
+use ILIAS\Data\Clock\LocalClock;
+use PHPUnit\Framework\TestCase;
+
+class LocalClockTest extends TestCase
+{
+    private string $default_timezone;
+
+    protected function setUp() : void
+    {
+        $this->default_timezone = date_default_timezone_get();
+    }
+
+    protected function tearDown() : void
+    {
+        date_default_timezone_set($this->default_timezone);
+    }
+
+    public function testUtcClockIsNotAffectedByGlobalTimezoneChanges() : void
+    {
+        date_default_timezone_set('UTC');
+
+        $clock = new LocalClock(new DateTimeZone('Africa/Windhoek'));
+
+        self::assertSame('Africa/Windhoek', $clock->now()->getTimezone()->getName());
+    }
+}
diff --git a/tests/Data/SystemClockTest.php b/tests/Data/SystemClockTest.php
new file mode 100644
index 000000000000..495c7df61931
--- /dev/null
+++ b/tests/Data/SystemClockTest.php
@@ -0,0 +1,44 @@
+<?php declare(strict_types=1);
+
+/******************************************************************************
+ *
+ * This file is part of ILIAS, a powerful learning management system.
+ *
+ * ILIAS is licensed with the GPL-3.0, you should have received a copy
+ * of said license along with the source code.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ *      https://www.ilias.de
+ *      https://github.com/ILIAS-eLearning
+ *
+ *****************************************************************************/
+
+namespace ILIAS\Data\Clock;
+
+use ILIAS\Data\Clock\SystemClock;
+use PHPUnit\Framework\TestCase;
+
+class SystemClockTest extends TestCase
+{
+    private string $default_timezone;
+
+    protected function setUp() : void
+    {
+        $this->default_timezone = date_default_timezone_get();
+    }
+
+    protected function tearDown() : void
+    {
+        date_default_timezone_set($this->default_timezone);
+    }
+
+    public function testUtcClockIsNotAffectedByGlobalTimezoneChanges() : void
+    {
+        date_default_timezone_set('Africa/Windhoek');
+
+        $clock = new SystemClock();
+
+        self::assertSame('Africa/Windhoek', $clock->now()->getTimezone()->getName());
+    }
+}
diff --git a/tests/Data/UtcClockTest.php b/tests/Data/UtcClockTest.php
new file mode 100644
index 000000000000..13f132cb2768
--- /dev/null
+++ b/tests/Data/UtcClockTest.php
@@ -0,0 +1,43 @@
+<?php declare(strict_types=1);
+
+/******************************************************************************
+ *
+ * This file is part of ILIAS, a powerful learning management system.
+ *
+ * ILIAS is licensed with the GPL-3.0, you should have received a copy
+ * of said license along with the source code.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ *      https://www.ilias.de
+ *      https://github.com/ILIAS-eLearning
+ *
+ *****************************************************************************/
+
+namespace ILIAS\Data\Clock;
+
+use ILIAS\Data\Clock\UtcClock;
+use PHPUnit\Framework\TestCase;
+
+class UtcClockTest extends TestCase
+{
+    private string $default_timezone;
+
+    protected function setUp() : void
+    {
+        $this->default_timezone = date_default_timezone_get();
+    }
+
+    protected function tearDown() : void
+    {
+        date_default_timezone_set($this->default_timezone);
+    }
+
+    public function testUtcClockIsNotAffectedByGlobalTimezoneChanges() : void
+    {
+        date_default_timezone_set('Europe/Berlin');
+        $clock = new UtcClock();
+
+        self::assertSame('UTC', $clock->now()->getTimezone()->getName());
+    }
+}