Merge pull request #13 from stevegrunwell/feature/multipliers

Add multipliers for sub-second timing

README.md

@@ -66,3 +66,16 @@ This is a list of all constants defined by this package, along with their values
 * `WEEK_IN_MINUTES` (10,080 minutes)
 * `MONTH_IN_MINUTES` (43,200 minutes)
 * `YEAR_IN_MINUTES` (525,600 minutes)
+
+### Multipliers
+
+These can be helpful when dealing with fractions of a second. For example, all of the following are equivalent:
+
+```php
+6000 === (6 * ONE_SECOND) * 1000 === 6 * MILLISECONDS_PER_SECOND
+```
+
+* `MILLISECONDS_PER_SECOND` (1,000ms/s)
+* `MICROSECONDS_PER_SECOND` (1,000,000µs/s)
+* `NANOSECONDS_PER_SECOND` (1,000,000,000ns/s)
+* `PICOSECONDS_PER_SECOND` (1,000,000,000,000ps/s)

constants.php

@@ -85,3 +85,29 @@
 if (! defined('YEAR_IN_MINUTES')) {
     define('YEAR_IN_MINUTES', 365 * DAY_IN_MINUTES);
 }
+
+/**
+ * Common multipliers.
+ *
+ * These are useful when dealing with timing and things like cache expirations.
+ */
+
+/* A millisecond is 1/1000 of a second. */
+if (! defined('MILLISECONDS_PER_SECOND')) {
+    define('MILLISECONDS_PER_SECOND', 1000);
+}
+
+/* A microsecond is one millionth of a second. */
+if (! defined('MICROSECONDS_PER_SECOND')) {
+    define('MICROSECONDS_PER_SECOND', 1000000);
+}
+
+/* A nanosecond is one billionth of a second. */
+if (! defined('NANOSECONDS_PER_SECOND')) {
+    define('NANOSECONDS_PER_SECOND', 1000000000);
+}
+
+/* A picosecond is one trillionth of a second. */
+if (! defined('PICOSECONDS_PER_SECOND')) {
+    define('PICOSECONDS_PER_SECOND', 1000000000000);
+}

tests/ConstantsTest.php

@@ -13,41 +13,51 @@
 class ConstantsTest extends TestCase
 {
     /**
-     * Ensure that each constant is defined and numeric.
+     * Ensure that each constant is defined and matches the expected value.
      *
-     * @dataProvider constantsProvider()
+     * @dataProvider constantsProvider
      *
-     * @param string $constant
+     * @param string $constant The name of the constant.
+     * @param int    $expected The expected value for the constant.
      *
      * @return void
      */
-    public function testConstantsAreDefined($constant)
+    public function testConstantsAreDefined(string $constant, int $expected): void
     {
-        $this->assertTrue(defined($constant), 'Expected the constant to be defined.');
-        $this->assertIsInt(constant($constant), 'Expected an integer value.');
+        $this->assertTrue(defined($constant), "Expected the '{$constant}' constant to be defined.");
+        $this->assertSame($expected, constant($constant));
     }
 
     /**
      * Provides a list of all constants defined by this package.
      *
-     * @return array
+     * @return array{string, int}
      */
-    public function constantsProvider()
+    public function constantsProvider(): array
     {
         return [
-            'One second (in seconds)'       => ['ONE_SECOND'],
-            'One minute (in seconds)'       => ['MINUTE_IN_SECONDS'],
-            'One hour (in seconds)'         => ['HOUR_IN_SECONDS'],
-            'One day (in seconds)'          => ['DAY_IN_SECONDS'],
-            'One week (in seconds'          => ['WEEK_IN_SECONDS'],
-            'One 30-day month (in seconds)' => ['MONTH_IN_SECONDS'],
-            'One year (in seconds)'         => ['YEAR_IN_SECONDS'],
-            'One minute (in minutes)'       => ['ONE_MINUTE'],
-            'One hour (in minutes)'         => ['HOUR_IN_MINUTES'],
-            'One day (in minutes)'          => ['DAY_IN_MINUTES'],
-            'One week (in minutes'          => ['WEEK_IN_MINUTES'],
-            'One 30-day month (in minutes)' => ['MONTH_IN_MINUTES'],
-            'One year (in minutes)'         => ['YEAR_IN_MINUTES'],
+            // Time in seconds.
+            'One second (in seconds)'       => ['ONE_SECOND', 1],
+            'One minute (in seconds)'       => ['MINUTE_IN_SECONDS', 60],
+            'One hour (in seconds)'         => ['HOUR_IN_SECONDS', 3600],
+            'One day (in seconds)'          => ['DAY_IN_SECONDS', 86400],
+            'One week (in seconds'          => ['WEEK_IN_SECONDS', 604800],
+            'One 30-day month (in seconds)' => ['MONTH_IN_SECONDS', 2592000],
+            'One year (in seconds)'         => ['YEAR_IN_SECONDS', 31536000],
+
+            // Time in minutes.
+            'One minute (in minutes)'       => ['ONE_MINUTE', 1],
+            'One hour (in minutes)'         => ['HOUR_IN_MINUTES', 60],
+            'One day (in minutes)'          => ['DAY_IN_MINUTES', 1440],
+            'One week (in minutes'          => ['WEEK_IN_MINUTES', 10080],
+            'One 30-day month (in minutes)' => ['MONTH_IN_MINUTES', 43200],
+            'One year (in minutes)'         => ['YEAR_IN_MINUTES', 525600],
+
+            // Multipliers.
+            'Milliseconds per second'       => ['MILLISECONDS_PER_SECOND', 1000],
+            'Microseconds per second'       => ['MICROSECONDS_PER_SECOND', 1000000],
+            'Nanoseconds per second'        => ['NANOSECONDS_PER_SECOND', 1000000000],
+            'Picoseconds per second'        => ['PICOSECONDS_PER_SECOND', 1000000000000],
         ];
     }
 }