Merge pull request #1254 from ashnazg/clock

Grammar, Spelling, Formatting

Author: Jean85

proposed/clock-meta.md

@@ -2,29 +2,29 @@
 
 ## 1. Summary
 
-Getting the current time in applications is typically achieved using the `time()` or `microtime` functions, or by using a `new \DateTimeImmutable()` class.
+Getting the current time in applications is typically achieved using the `\time()` or `\microtime` functions, or by using a `new \DateTimeImmutable()` class.
 
-Due to the nature of time progression these methods cannot be used when predictable results are needed, such as during testing.
+Due to the nature of time progression, these methods cannot be used when predictable results are needed, such as during testing.
 
-This `ClockInterface` aims to provide a standard way to consume time that allows interoperability not only when consuming the "real" time but also when predictable results need to be available. This avoids the need to use PHP extensions for testing or redeclare the `time()` function in a local namespace. 
+This `ClockInterface` aims to provide a standard way to consume time that allows interoperability, not only when consuming the "real" time, but also when predictable results need to be available. This avoids the need to use PHP extensions for testing or redeclaring the `\time()` function in a local namespace.
 
 ## 2. Why Bother?
 
-There are currently a few libraries that provide this functionality, however there is no interopability between these different libraries, as they ship with their own clock interfaces. 
+There are currently a few libraries that provide this functionality. However, there is no interoperability between these different libraries, as they ship with their own clock interfaces.
 
-Symfony provides a package called `symfony/phpunit-bridge` that has a `Symfony\Bridge\PhpUnit\ClockMock` class, which allows mocking PHP's built-in time and date functions, however this does not solve mocking calls to `new \DateTimeImmutable()`. It also does not fully mock time when called from other libraries that rely on the system time.
+Symfony provides a package called `symfony/phpunit-bridge` that has a `\Symfony\Bridge\PhpUnit\ClockMock` class, which allows mocking PHP's built-in time and date functions. However, this does not solve mocking calls to `new \DateTimeImmutable()`. It also does not fully mock time when called from other libraries that rely on the system time.
 
-`Carbon\Carbon`, and its fork `Cake\Chronos\Chronos`, do provide mocking via a static `setTestNow()` method, but this provides no isolation and must be called again to stop mocking.
+`\Carbon\Carbon`, and its fork `\Cake\Chronos\Chronos`, do provide mocking via a static `setTestNow()` method, but this provides no isolation and must be called again to stop mocking.
 
 Pros:
 
 * Consistent interface to get the current time;
-* Easy to mock the wall clock time for repeatablility.
+* Easy to mock the wall clock time for repeatability.
 
 Cons:
 
-* Extra overhead and developer effort to get the current time, not as simple as
-calling `time()` or `date()`.
+* Extra overhead and developer effort to get the current time;
+* Not as simple as calling `\time()` or `\date()`.
 
 ## 3. Scope
 
@@ -35,17 +35,15 @@ calling `time()` or `date()`.
 
 ### 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 recommendation on how to handle timezones when 
-  retrieving the current time. This is left up to the implementation.
+* 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 recommendation on how to handle timezones when retrieving the current time. This is left up to the implementation.
 * This PSR does not handle any scheduling methods like `sleep()` or `wait()` because such methods are not related to retrieving the current time.
 
 ## 4. Approaches
 
 ### 4.1 Chosen Approach
 
-We have decided to formalize the existing practices used by several other packages. Some popular packages providing this functionality are: 
+We have decided to formalize the existing practices used by several other packages. Some popular packages providing this functionality are:
 
 * [`lcobucci/clock`](https://packagist.org/packages/lcobucci/clock)
 * [`kreait/clock`](https://packagist.org/packages/kreait/clock)
@@ -54,18 +52,17 @@ We have decided to formalize the existing practices used by several other packag
 
 (This list is not exhaustive!)
 
-Some of these provide interfaces and some rely on extending a clock class to mock the
-current time.
+Some of these provide interfaces and some rely on extending a clock class to mock the current time.
 
-These implementations all provide a `now()` method which returns a `DateTimeImmutable` object. As the `DateTimeImmutable` object allows retrieving the Unix timestamp, by calling `getTimestamp()` or `format('u.U')`, this interface does not define any special methods to retrieve a Unix timestamp or any other time information that is not available from a `DateTimeImmutable` object. 
+These implementations all provide a `now()` method which returns a `\DateTimeImmutable` object. As the `\DateTimeImmutable` object allows retrieving the Unix timestamp, by calling `getTimestamp()` or `format('u.U')`, this interface does not define any special methods to retrieve a Unix timestamp or any other time information that is not available from a `\DateTimeImmutable` object.
 
 ### 4.2 Timezones
 
-Time by now is defined by interaction of electromagnetic radiation with the excited states of certain atoms where the SI defines one second as the duration of 9192631770 cycles of radiation corresponding to the transition between two energy levels of the ground state of the caesium-133 atom at 0K. This means that retrieving the current time will always return the same time, no matter where it is observed. While the timezone defines *where* the time was observed it does not modify the actual "slice" of time.
+Time by now is defined by interaction of electromagnetic radiation with the excited states of certain atoms, where the SI defines one second as the duration of 9192631770 cycles of radiation corresponding to the transition between two energy levels of the ground state of the caesium-133 atom at 0K. This means that retrieving the current time will always return the same time, no matter where it is observed. While the timezone defines *where* the time was observed, it does not modify the actual "slice" of time.
 
-This means that for the sake of this PSR the timezone is considered an implementation detail of the interface. 
+This means that, for the sake of this PSR, the timezone is considered an implementation detail of the interface.
 
-It is up to the implementation to make sure that the timezone is handled according to the business logic of the application. That is either by making sure that a call to `now()` will only return a `DateTimeImmutable` object with a known timezone (implicit contract) or by explicitly changing the timezone to be correct for the application. This can be done by calling `setTimezone()` to create a new `DateTimeImmutable` object with the given timezone. 
+It is up to the implementation to make sure that the timezone is handled according to the business logic of the application. That is either by making sure that a call to `now()` will only return a `\DateTimeImmutable` object with a known timezone (implicit contract) or by explicitly changing the timezone to be correct for the application. This can be done by calling `setTimezone()` to create a new `\DateTimeImmutable` object with the given timezone.
 
 These actions are not defined in this interface.
 
@@ -135,7 +132,7 @@ final class FrozenClock implements \Psr\Clock\ClockInterface
 
 This document stems from the work of many people in previous years, we recognize their effort:
 
- * 
+ *
 _**Note:** Order descending chronologically._
 
 ## 9. FAQ

proposed/clock.md

@@ -8,7 +8,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
 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
+functionality than the one proposed, but they MUST implement the indicated
 interfaces/functionality first.
 
 [RFC 2119]: http://tools.ietf.org/html/rfc2119
@@ -17,10 +17,10 @@ interfaces/functionality first.
 
 ## 1.1 Introduction
 
-Creating a standard way of accessing the clock would allow interopability
-during testing, when testing behavior that has timing based side effects.
+Creating a standard way of accessing the clock would allow interoperability
+during testing, when testing behavior that has timing-based side effects.
 Common ways to get the current time include calling `\time()` or 
-`new DateTimeImmutable('now')`. However, this makes mocking the current time
+`new \DateTimeImmutable('now')`. However, this makes mocking the current time
 impossible in some situations.
 
 ## 1.2 Definitions
@@ -32,11 +32,9 @@ 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:
+This should be done by using the `getTimestamp()` method on the returned `\DateTimeImmutable`:
 ```php
 $timestamp = $clock->now()->getTimestamp();
 ```
@@ -45,10 +43,10 @@ $timestamp = $clock->now()->getTimestamp();
 
 ## 2.1 ClockInterface
 
-The clock interface defines the most basic operation to read the current time and date from the clock. 
-It MUST return the time as a `DateTimeImmutable`.
+The clock interface defines the most basic operations to read the current time and date from the clock. 
+It MUST return the time as a `\DateTimeImmutable`.
 
-~~~php
+```php
 <?php
 
 namespace Psr\Clock;
@@ -61,4 +59,4 @@ interface ClockInterface
     public function now(): \DateTimeImmutable;
 
 }
-~~~
+```