Merge pull request #4004 from mjansenDatabay/feature/8/clock-service

Clock: Introduce `PSR-20 Clock Service` as `src/Data` type

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;
 
 /******************************************************************************
  *

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;
+}

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);
+    }
+}

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;
+}

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);
+    }
+}

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');
+    }
+}

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'));
+    }
+}

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();
+    }
 }

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();
+?>
+```

src/Data/ROADMAP.md

@@ -0,0 +1 @@
+# Roadmap

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());
+    }
+}