Merge pull request #17 from adhocore/develop

Release 1.0

Author: adhocore

.travis.yml

@@ -1,16 +1,11 @@
 language: php
 
 php:
-  - 5.6
   - 7.0
   - 7.1
   - 7.2
   - 7.3
-  - nightly
-
-matrix:
-  allow_failures:
-    - php: nightly
+  - 7.4
 
 install:
   - composer install --prefer-dist

README.md

@@ -10,15 +10,16 @@
 
 - Lightweight Cron expression parser library for PHP.
 - Very **fast** because it bails early in case a segment doesnt match.
-- Supports PHP5.4 (if you are old school) to PHP7.3 (if you are cool).
 - Real [benchmark](https://github.com/adhocore/php-cron-bench) shows it is about 9.64x to 10.57x faster than `dragonmantank/cron-expression`
 
 ## Installation
 
 ```bash
 composer require adhocore/cron-expr
-```
 
+# PHP5.6 or lower
+composer require adhocore/cron-expr:0.1.0
+```
 
 ## Usage
 
@@ -63,9 +64,6 @@ $expr = new Expression;
 $dueJobs = $expr->filter($jobs, time());
 ```
 
-### Stabillity
-Although not yet in v1.0, but the library and the API it provides is pretty stable and will not be changed too broadly.
-
 ### Real Abbreviations
 
 You can use real abbreviations for month and week days. eg: `JAN`, `dec`, `fri`, `SUN`
@@ -95,3 +93,11 @@ Following modifiers supported
 - *Day of Week / 5th segment:*
 	- `L` stands for last weekday of month (eg: `2L` is last monday)
 	- `#` stands for nth day of week in the month (eg: `1#2` is second sunday)
+
+## LICENSE
+
+> © [MIT](./LICENSE) | 2017-2019, Jitendra Adhikari
+
+## Credits
+
+This project is release managed by [please](https://github.com/adhocore/please).

composer.json

@@ -27,5 +27,9 @@
     },
     "require-dev": {
         "phpunit/phpunit": "^4.8 || ^5.7 || ^6.5"
+    },
+    "scripts": {
+        "test": "vendor/bin/phpunit",
+        "test:cov": "vendor/bin/phpunit --coverage-text --coverage-clover coverage.xml"
     }
 }

src/Expression.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 /*
  * This file is part of the PHP-CRON-EXPR package.
  *
@@ -72,7 +74,7 @@ public function __construct(SegmentChecker $checker = null)
         }
     }
 
-    public static function instance()
+    public static function instance(): self
     {
         if (null === static::$instance) {
             static::$instance = new static;
@@ -85,11 +87,11 @@ public static function instance()
      * Parse cron expression to decide if it can be run on given time (or default now).
      *
      * @param string $expr The cron expression.
-     * @param int    $time The timestamp to validate the cron expr against. Defaults to now.
+     * @param mixed  $time The timestamp to validate the cron expr against. Defaults to now.
      *
      * @return bool
      */
-    public static function isDue($expr, $time = null)
+    public static function isDue(string $expr, $time = null): bool
     {
         return static::instance()->isCronDue($expr, $time);
     }
@@ -102,7 +104,7 @@ public static function isDue($expr, $time = null)
      *
      * @return array Due job names: [job1name, ...];
      */
-    public static function getDues(array $jobs, $time = null)
+    public static function getDues(array $jobs, $time = null): array
     {
         return static::instance()->filter($jobs, $time);
     }
@@ -117,7 +119,7 @@ public static function getDues(array $jobs, $time = null)
      *
      * @return bool
      */
-    public function isCronDue($expr, $time = null)
+    public function isCronDue(string $expr, $time = null): bool
     {
         list($expr, $times) = $this->process($expr, $time);
 
@@ -142,7 +144,7 @@ public function isCronDue($expr, $time = null)
      *
      * @return array Due job names: [job1name, ...];
      */
-    public function filter(array $jobs, $time = null)
+    public function filter(array $jobs, $time = null): array
     {
         $dues = $cache = [];
         $time = $this->normalizeTime($time);
@@ -168,9 +170,9 @@ public function filter(array $jobs, $time = null)
      * @param string $expr
      * @param mixed  $time
      *
-     * @return array
+     * @return array [expr, time]
      */
-    protected function process($expr, $time)
+    protected function process(string $expr, $time): array
     {
         $expr = $this->normalizeExpr($expr);
         $expr = \preg_split('~\s+~', $expr); // 14
@@ -187,7 +189,7 @@ protected function process($expr, $time)
         return [$expr, $times];
     }
 
-    protected function normalizeTime($time)
+    protected function normalizeTime($time): int
     {
         if (empty($time)) {
             $time = \time();
@@ -200,7 +202,7 @@ protected function normalizeTime($time)
         return $time;
     }
 
-    protected function normalizeExpr($expr)
+    protected function normalizeExpr(string $expr): string
     {
         $expr = \trim($expr);
 

src/SegmentChecker.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 /*
  * This file is part of the PHP-CRON-EXPR package.
  *
@@ -37,19 +39,12 @@ public function __construct(Validator $validator = null)
      *
      * @return bool
      */
-    public function checkDue($segment, $pos, $times)
+    public function checkDue(string $segment, int $pos, array $times): bool
     {
-        $isDue   = true;
         $offsets = \explode(',', \trim($segment));
 
         foreach ($offsets as $offset) {
-            if (null === $isDue = $this->isOffsetDue($offset, $pos, $times)) {
-                throw new \UnexpectedValueException(
-                    sprintf('Invalid offset value at segment #%d: %s', $pos, $offset)
-                );
-            }
-
-            if ($isDue) {
+            if ($this->isOffsetDue($offset, $pos, $times)) {
                 return true;
             }
         }
@@ -64,9 +59,9 @@ public function checkDue($segment, $pos, $times)
      * @param int    $pos
      * @param array  $times
      *
-     * @return bool|null
+     * @return bool
      */
-    protected function isOffsetDue($offset, $pos, $times)
+    protected function isOffsetDue(string $offset, int $pos, array $times): bool
     {
         if (\strpos($offset, '/') !== false) {
             return $this->validator->inStep($times[$pos], $offset);
@@ -83,7 +78,7 @@ protected function isOffsetDue($offset, $pos, $times)
         return $this->checkModifier($offset, $pos, $times);
     }
 
-    protected function checkModifier($offset, $pos, $times)
+    protected function checkModifier(string $offset, int $pos, array $times): bool
     {
         $isModifier = \strpbrk($offset, 'LCW#');
 
@@ -95,6 +90,6 @@ protected function checkModifier($offset, $pos, $times)
             return $this->validator->isValidWeekDay($offset, $times);
         }
 
-        return null;
+        $this->validator->unexpectedValue($pos, $offset);
     }
 }

src/Validator.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 /*
  * This file is part of the PHP-CRON-EXPR package.
  *
@@ -28,7 +30,7 @@ class Validator
      *
      * @return bool
      */
-    public function inRange($value, $offset)
+    public function inRange(int $value, string $offset): bool
     {
         $parts = \explode('-', $offset);
 
@@ -43,7 +45,7 @@ public function inRange($value, $offset)
      *
      * @return bool
      */
-    public function inStep($value, $offset)
+    public function inStep(int $value, string $offset): bool
     {
         $parts = \explode('/', $offset, 2);
 
@@ -58,7 +60,7 @@ public function inStep($value, $offset)
         $parts    = \explode('/', $offset, 2);
         $subparts = \explode('-', $parts[0], 2) + [1 => $value];
 
-        return $this->inStepRange($value, $subparts[0], $subparts[1], $parts[1]);
+        return $this->inStepRange((int) $value, (int) $subparts[0], (int) $subparts[1], (int) $parts[1]);
     }
 
     /**
@@ -71,7 +73,7 @@ public function inStep($value, $offset)
      *
      * @return bool
      */
-    public function inStepRange($value, $start, $end, $step)
+    public function inStepRange(int $value, int $start, int $end, int $step): bool
     {
         if (($start + $step) > $end) {
             return false;
@@ -92,31 +94,33 @@ public function inStepRange($value, $start, $end, $step)
      * @param string $value
      * @param array  $time
      *
-     * @return bool|null
+     * @return bool
      */
-    public function isValidMonthDay($value, $time)
+    public function isValidMonthDay(string $value, array $time): bool
     {
         if ($value == 'L') {
             return $time[2] == $time[6];
         }
 
         if ($pos = \strpos($value, 'W')) {
             $value = \substr($value, 0, $pos);
-            $month = \str_pad($time[8], 2, '0', \STR_PAD_LEFT);
+            $month = $this->zeroPad($time[8]);
 
-            return $this->isClosestWeekDay($value, $month, $time);
+            return $this->isClosestWeekDay((int) $value, $month, $time);
         }
+
+        $this->unexpectedValue(2, $value);
     }
 
-    protected function isClosestWeekDay($value, $month, $time)
+    protected function isClosestWeekDay(int $value, string $month, array $time): bool
     {
         foreach ([0, -1, 1, -2, 2] as $i) {
             $incr = $value + $i;
             if ($incr < 1 || $incr > $time[6]) {
                 continue;
             }
 
-            $incr  = \str_pad($incr, 2, '0', \STR_PAD_LEFT);
+            $incr  = $this->zeroPad($incr);
             $parts = \explode(' ', \date('N m j', \strtotime("{$time[5]}-$month-$incr")));
             if ($parts[0] < 6 && $parts[1] == $month) {
                 return $time[2] == $parts[2];
@@ -136,30 +140,43 @@ protected function isClosestWeekDay($value, $month, $time)
      * @param string $value
      * @param array  $time
      *
-     * @return bool|null
+     * @return bool
      */
-    public function isValidWeekDay($value, $time)
+    public function isValidWeekDay(string $value, array $time): bool
     {
-        $month = \str_pad($time[8], 2, '0', \STR_PAD_LEFT);
+        $month = $this->zeroPad($time[8]);
 
         if (\strpos($value, 'L')) {
             return $this->isLastWeekDay($value, $month, $time);
         }
 
         if (!\strpos($value, '#')) {
-            return null;
+            $this->unexpectedValue(4, $value);
         }
 
         list($day, $nth) = \explode('#', \str_replace('0#', '7#', $value));
 
-        if (!$this->isNthWeekDay($day, $nth) || $time[9] != $day) {
+        if (!$this->isNthWeekDay((int) $day, (int) $nth) || $time[9] != $day) {
             return false;
         }
 
         return \intval($time[7] / 7) == $nth - 1;
     }
 
-    protected function isLastWeekDay($value, $month, $time)
+    /**
+     * @param int    $pos
+     * @param string $value
+     *
+     * @throws \UnexpectedValueException
+     */
+    public function unexpectedValue(int $pos, string $value)
+    {
+        throw new \UnexpectedValueException(
+            \sprintf('Invalid offset value at segment #%d: %s', $pos, $value)
+        );
+    }
+
+    protected function isLastWeekDay(string $value, string $month, array $time): bool
     {
         $value = \explode('L', \str_replace('7L', '0L', $value));
         $decr  = $time[6];
@@ -174,8 +191,13 @@ protected function isLastWeekDay($value, $month, $time)
         return false;
     }
 
-    protected function isNthWeekDay($day, $nth)
+    protected function isNthWeekDay(int $day, int $nth): bool
     {
         return !($day < 0 || $day > 7 || $nth < 1 || $nth > 5);
     }
+
+    protected function zeroPad($value): string
+    {
+        return \str_pad((string) $value, 2, '0', \STR_PAD_LEFT);
+    }
 }