New PSR for ClockInterface

proposed/clock-meta.md

@@ -0,0 +1,154 @@
+# PHPDoc Meta Document
+
+## 1. Summary
+
+The purpose of using the ClockInterface is to provide a standard way to access the system 
+time, that would allow interopability when testing code that relies on the current time 
+rather than relying installing PHP extensions or use hacks like re-declaring the time() 
+function in other namespaces. 
+
+## 2. Why Bother?
+
+There are currently a few libraries that do provide the functionality on packagist, however 
+there is no interopability between these different libraries, as they ship with their own 
+clock interfaces. Symfony has a TimeMock library which uses namespace hacks to override the 
+`time()`, `date()`, `microtime()`, etc functions, however this does not solve mocking calls to 
+`new \DateTime()`
+
+Pros:
+
+* Consistent interface to get the current time
+* Easy to mock the wall clock time for repeatablility.
+
+Cons:
+
+* Extra overhead and developer effort to get the current time, not as simple as
+calling `time()` or `date()`.
+
+## 3. Scope
+
+### 3.1 Goals
+
+* Provide a simple and mockable way to read the current time
+* Allow interoperability between libraries when reading the clock
+
+### 3.2 Non-Goals
+
+* This PSR does not provide a recommendation on how and when to use the concepts
+  described in this document, so it is not a coding standard.
+* This PSR does not provide a reccomendation on how to handle timezones when 
+  retrieving the current time. This is left up to the implementation.
+
+## 4. Approaches
+
+### 4.1 Chosen Approach
+
+We have decided to formalize the existing practices, use by several other packages
+out in the wild. Some of the popular packages providing this functionality are: 
+lcobucci/clock, kreait/clock, ergebnis/clock, and mangoweb/clock. Some providing
+interfaces, and some relying on overloading (extending) the Clock class to mock the
+current time.
+
+
+### 4.2 Example Implemntations
+
+```php
+final class TimeZoneAwareClock implements \Psr\Clock\ClockInterface
+{
+    private DateTimeZone $timeZone;
+
+    public function __construct(DateTimeZone $timeZone)
+    {
+        $this->timeZone = $timeZone;
+    }
+
+    public function now(): \DateTimeImmutable
+    {
+        return new DateTimeImmutable('now', $this->timeZone);
+    }
+}
+
+//
+
+final class SystemClock implements \Psr\Clock\ClockInterface
+{
+
+    public function now(): \DateTimeImmutable
+    {
+        return new \DateTimeImmutable();
+    }
+}
+
+//
+
+final class UTCClock implements \Psr\Clock\ClockInterface
+{
+    private TimeZoneAwareClock $inner;
+
+    public function __construct()
+    {
+        $this->inner = new TimeZoneAwareClock(new DateTimeZone('UTC'));
+    }
+
+    public function now(): \DateTimeImmutable
+    {
+        return $this->inner->now();
+    }
+}
+
+//
+
+final class FrozenClock implements \Psr\Clock\ClockInterface
+{
+    private DateTimeImmutable $now;
+
+    public function __construct(DateTimeImmutable $now)
+    {
+        $this->now = $now;
+    }
+
+    public function now(): \DateTimeImmutable
+    {
+        return $this->now;
+    }
+}
+```
+
+## 5. People
+
+### 5.1 Editor
+
+ * Chris Seufert
+
+### 5.2 Sponsor
+
+ * Chuck Burgess
+
+### 5.3 Working group members
+
+ * Pol Dellaiera
+ * Ben Edmunds
+ * Jérôme Gamez
+ * Andreas Heigl
+ * Andreas Möller
+ * Luís Cobucci
+
+## 6. Votes
+
+* 
+
+## 7. Relevant Links
+* https://github.com/ergebnis/clock/blob/main/src/Clock.php
+* https://github.com/icecave/chrono/blob/master/src/Clock/ClockInterface.php
+* https://github.com/Kdyby/DateTimeProvider/blob/master/src/DateTimeProviderInterface.php
+* https://github.com/kreait/clock-php/blob/main/src/Clock.php
+* https://github.com/lcobucci/clock/blob/2.1.x/src/Clock.php
+* https://github.com/mangoweb-backend/clock/blob/master/src/Clock.php
+* https://martinfowler.com/bliki/ClockWrapper.html
+
+## 8. Past contributors
+
+Since this document stems from the work of a lot of people in previous years, we should recognize their effort:
+
+ * 
+_**Note:** Order descending chronologically._

proposed/clock.md

@@ -0,0 +1,72 @@
+Common Interface for Accessing the Clock
+========================================
+
+This document describes a simple interface for reading the system clock.
+
+The key words "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][].
+
+The final implementations MAY decorate the objects with more
+functionality than the one proposed but they MUST implement the indicated
+interfaces/functionality first.
+
+[RFC 2119]: http://tools.ietf.org/html/rfc2119
+
+# 1. Specification
+
+## 1.1 Introduction
+
+Creating a standard way of accessing the clock, would allow interopability
+during testing, when testing behavior that has timing based side affects.
+Common ways to get the current time include calling `\time()` or 
+`new DateTimeImmutable('now')` however this makes mocking the current time
+impossible in some situations.
+
+## 1.2 Definitions
+
+* **Clock** - The clock is able to read the current time and date.
+
+* **Timestamp** - The current time as an integer number of seconds since
+Jan 1, 1970 00:00:00 UTC.
+
+### 1.3 Usage
+
+There are some common usage patterns, which are outlined below:
+
+**Get the current timestamp**
+
+This should be done by using the `getTimestamp()` method on the returned `\DateTimeImmutable` like so:
+```php
+$timestamp = $clock->now()->getTimestamp();
+```
+
+**Timezone**
+
+Each implementation of the `ClockInterface` is free to return the time in the 
+timezone of that library authors choice. This could include but not be limited 
+to return the current PHP timezone (as DateTimeImmutable consructor currently
+does), return a timezone set a the creation of the ClockInterface implementation
+instance, or always returning a fixed timzone (eg UTC).
+
+# 2. Interfaces
+
+## 2.1 ClockInterface
+
+The clock interface defines the most basic operations to read the current time and date from the clock. 
+It MUST return the current time as a DateTimeImmutable.
+
+~~~php
+<?php
+
+namespace Psr\Clock;
+
+interface ClockInterface
+{
+    /**
+     * Returns the current time as a DateTimeImmutable Object
+     */
+    public function now(): \DateTimeImmutable;
+
+}
+~~~