New PSR for ClockInterface

proposed/clock-meta.md

@@ -0,0 +1,81 @@
+# PHPDoc Meta Document
+
+## 1. Summary
+
+The purpose of using the ClockInterface would allow mocking time in many situations where
+you cant easily install PHP extenions or use hacks like re-declaring the time() funciton
+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 thier own 
+clock interfaces. Symphony 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 effor to get the current time, not as simple as
+calling `time()` or `date()`.
+
+## 3. Scope
+
+### 3.1 Goals
+
+* Provide a simple way mockable way to read the current time
+* Allow interopability 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.
+
+## 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, some relying on overloading a class to mock the current time.
+
+## 5. People
+
+### 5.1 Editor
+
+ * Chris Seufert
+
+### 5.2 Sponsor
+
+ * 
+
+### 5.3 Working group members
+
+ * 
+
+## 6. Votes
+
+* 
+
+## 7. Relevant Links
+
+* https://github.com/lcobucci/clock/blob/2.1.x/src/Clock.php
+* https://github.com/kreait/clock-php/blob/main/src/Clock.php
+* https://github.com/ergebnis/clock/blob/main/src/Clock.php
+* https://github.com/mangoweb-backend/clock/blob/master/src/Clock.php
+* https://github.com/icecave/chrono/blob/master/src/Clock/ClockInterface.php
+* https://github.com/Kdyby/DateTimeProvider/blob/master/src/DateTimeProviderInterface.php
+
+## 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,86 @@
+Common Interface for Accessing the Clock
+========================================
+
+This document describes a simple yet extensible interface for a cache item and
+a cache driver.
+
+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.
+
+# 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, DateTime, timestamp integer and timestamp float, 
+and MUST return the current time zone.
+
+~~~php
+<?php
+
+namespace Psr\Clock;
+
+interface ClockInterface
+{
+    /**
+     * Reads the current time as a unix timestamp
+     *
+     * @return int The current time as a unix timestamp
+     */
+    public function timestamp():int;
+
+    /**
+     * Reads the current time as a DateTimeImmutable Object
+     *
+     * @return \DateTimeImmutable The current time as a DateTimeImmutable Object
+     */
+    public function immutable():\DateTimeImmutable;
+
+
+    /**
+     * Reads the current time as a DateTime Object
+     *
+     * @return \DateTime The current time as a DateTime Object
+     */
+    public function datetime():\DateTime
+
+    /**
+     * Reads the current time as with microsecond resolution
+     *
+     * @return float The current time as a float with microsecond resolution
+     */
+     public function microtime():float
+
+    /**
+     * Retreieves the current time zone
+     *
+     * @return \DateTimeZone The current timezone as a DateTimeZone object
+     */
+     public function timezone():\DateTimeZone
+
+}
+~~~