Run jobs at specific date (#70)

* Run jobs on a specific date

* Documented all of the interval helpers

* StyleCI fixes

Author: peppeocchi

README.md

@@ -145,6 +145,51 @@ If you don't call any of this method, the job will run every minute (* * * * *).
     $scheduler->php('script.php')->daily('22:03');
     ```
 
+There are additional helpers for weekdays (all accepting optionals hour and minute - defaulted at 00:00)
+- `sunday`
+- `monday`
+- `tuesday`
+- `wednesday`
+- `thursday`
+- `friday`
+- `saturday`
+
+```php
+$scheduler->php('script.php')->saturday();
+$scheduler->php('script.php')->friday(18);
+$scheduler->php('script.php')->sunday(12, 30);
+```
+
+And additional helpers for months (all accepting optionals day, hour and minute - defaulted to the 1st of the month at 00:00)
+- `january`
+- `february`
+- `march`
+- `april`
+- `may`
+- `june`
+- `july`
+- `august`
+- `september`
+- `october`
+- `november`
+- `december`
+
+```php
+$scheduler->php('script.php')->january();
+$scheduler->php('script.php')->december(25);
+$scheduler->php('script.php')->august(15, 20, 30);
+```
+
+You can also specify a `date` for when the job should run.
+The date can be specified as string or as instance of `DateTime`. In both cases you can specify the date only (e.g. 2018-01-01) or the time as well (e.g. 2018-01-01 10:30), if you don't specify the time it will run at 00:00 on that date.
+If you're providing a date in a "non standard" format, it is strongly adviced to pass an instance of `DateTime`. If you're using `createFromFormat` without specifying a time, and you want to default it to 00:00, just make sure to add a `!` to the date format, otherwise the time would be the current time. [Read more](http://php.net/manual/en/datetime.createfromformat.php)
+
+```php
+$scheduler->php('script.php')->date('2018-01-01 12:20');
+$scheduler->php('script.php')->date(new DateTime('2018-01-01'));
+$scheduler->php('script.php')->date(DateTime::createFromFormat('!d/m Y', '01/01 2018'));
+```
+
 ### Send output to file/s
 
 You can define one or multiple files where you want the output of your script/command/function execution to be sent to.

src/GO/Job.php

@@ -51,6 +51,13 @@ class Job
      */
     private $executionTime;
 
+    /**
+     * Job schedule year.
+     *
+     * @var string
+     */
+    private $executionYear = null;
+
     /**
      * Temporary directory path for
      * lock files to prevent overlapping.
@@ -193,6 +200,10 @@ public function isDue(DateTime $date = null)
 
         $date = $date !== null ? $date : $this->creationTime;
 
+        if ($this->executionYear && $this->executionYear !== $date->format('Y')) {
+            return false;
+        }
+
         return $this->executionTime->isDue($date);
     }
 

src/GO/Traits/Interval.php

@@ -1,5 +1,6 @@
 <?php namespace GO\Traits;
 
+use DateTime;
 use Cron\CronExpression;
 use InvalidArgumentException;
 
@@ -18,6 +19,23 @@ public function at($expression)
         return $this;
     }
 
+    /**
+     * Run the Job at a specific date.
+     *
+     * @param  string/DateTime  $date
+     * @return self
+     */
+    public function date($date)
+    {
+        if (! $date instanceof DateTime) {
+            $date = new DateTime($date);
+        }
+
+        $this->executionYear = $date->format('Y');
+
+        return $this->at("{$date->format('i')} {$date->format('H')} {$date->format('d')} {$date->format('m')} *");
+    }
+
     /**
      * Set the execution time to every minute.
      *

tests/GO/IntervalTest.php

@@ -228,4 +228,40 @@ public function testShouldRunMonthlyOnCustomDayAndTime()
         $this->assertTrue($job->monthly(null, 15, '12:21')->isDue($date2));
         $this->assertFalse($job->monthly(null, 15, '12:21')->isDue($date3));
     }
+
+    public function testShouldRunAtSpecificDate()
+    {
+        $job = new Job('ls');
+
+        $date = '2018-01-01';
+
+        // As instance of datetime
+        $this->assertTrue($job->date(new \DateTime($date))->isDue(new \DateTime($date)));
+        // As date string
+        $this->assertTrue($job->date($date)->isDue(new \DateTime($date)));
+        // Fail for different day
+        $this->assertFalse($job->date($date)->isDue(new \DateTime('2018-01-02')));
+    }
+
+    public function testShouldRunAtSpecificDateTime()
+    {
+        $job = new Job('ls');
+
+        $date = '2018-01-01 12:20';
+
+        // As instance of datetime
+        $this->assertTrue($job->date(new \DateTime($date))->isDue(new \DateTime($date)));
+        // As date string
+        $this->assertTrue($job->date($date)->isDue(new \DateTime($date)));
+        // Fail for different time
+        $this->assertFalse($job->date($date)->isDue(new \DateTime('2018-01-01 12:21')));
+    }
+
+    public function testShouldFailIfDifferentYear()
+    {
+        $job = new Job('ls');
+
+        // As instance of datetime
+        $this->assertFalse($job->date('2018-01-01')->isDue(new \DateTime('2019-01-01')));
+    }
 }