New features for custom job/scheduler running times (#29)

* Clean up

* Updated phpunit

* Refactoring for v2

* Refectory for v2 pt2

* Required dev php7

Phpunit v6 requires php7 to run

* Fancy helpers

* Prioritise jobs in background

* Use temp arrays to prioritise jobs

* Coveralls

* Coverall config

* Adjusted waiting time on test

* Typo fix

* Removed deprecated flag

* Added Coverage badge to readme

* Removed psr/log suggestion

* Fixed typo in composer.json

* Fixes from styleci

* Downgraded phpunit

Using an older version of phpunit to allow testing on php5, as phpunit
v6 requires php7

* Added php 7.1 supported version

* More fixes from styleci

* Fixes from styleci

* Reordered badges + styleci badge

* Increased tests waiting time when testing file output

* Typo in the documentation

Ref #16

* Fix #20

Added support for SwiftMailer ^6.0

::newInstance() method has been deprecated, along with
Swift_MailTransport.

The default mail transport is now sendmail when using swiftmailer

https://legalhackers.com/advisories/SwiftMailer-Exploit-Remote-Code-Exec
-CVE-2016-10074-Vuln.html

* Implementation of #23 using `then` method

Similar implementation of the PR #23 submitted by @badyto

Reused the same tests on that PR

There is also a possible breaking change with the output passed to the
callback in the `then` method, when executing a script the output will
be now an array instead of a string.

* Added scheduler test

This test ensures that if a job is delayed by e.g. a previous job, it
will run if it was due when the scheduler ran.

* Removed comment from test

*  Allow run() to be executed multiple times  (#24)

* Allow run() to be executed multiple times

The current code expects the run() to be called only once. This is
fine if you start the scheduler from cron each minute and re-initialize
it each time. If you want to manually run the scheduler, or maybe
have a lot of jobs you do not want to init each minute, it would
be useful to call run() multiple times in the lifetime of the
scheduler.

In this case the collected data of the last run should be reset.
the executedJobs, failedJobs and outputSchedule.

* Allow queued jobs to be removed

If the scheduler is used to do multiple runs then it would be useful
to reset all queued Jobs. Currently the only way to do this is by
re-creating the scheduler object. But if the object is injected in the
code then this is not practical..

* Fix StyleCI analysis failure

Comment format fixed.

* Allow run() to be executed multiple times

After discussion with @peppeocchi make the re-running manually
triggered. So added a resetRun() method which can be called before
each run(). Also adjusted the test for this.

* Allow run() to be executed multiple times

The isDue check on the jobs is not provided a datetime in the run()
method. This means they use the creation time of the job as the
'current' time to compare against.

Most likely this creation time is approx the time run() is called so
normally this is no problem. But if setting up the job schedule takes
more time then I would say, using the creation time as run time is
unexpected. And if you run run() multiple times then it will always
run the same jobs because the time never changes.

So now provide an explicit run time for all jobs, which is the same
for all jobs each run.

* Fix StyleCI analysis failure

Remove empty line

* Allow run() to run at arbitrary time (#28)

Currently when run() is called it uses the current time as the run
timestamp. However it would be useful to run the scheduler at a
specific time. So allow an optional param with a DateTime to run().

Reasons for running at a specific time other than now() could be:

- Catching up on 'missed' runs, eg. when the system was down.

- Making sure the scheduler runs at an intended timestamp eg. when
cron is started at midnight it could be slow and start the php process
only at 00:01 and thus missing all midnight schedules.

- Improve testability of the scheduler (fake the time)

* Minor change + documentation new features

README.md

@@ -295,3 +295,33 @@ $scheduler->php('script.php')->then(function ($output) {
     log('Job executed!');
 }, true);
 ```
+
+### Multiple scheduler runs
+In some cases you might need to run the scheduler multiple times in the same script.
+Although this is not a common case, the following methods will allow you to re-use the same instance of the scheduler.
+```php
+# some code
+$scheduler->run();
+# ...
+
+// Reset the scheduler after a previous run
+$scheduler->resetRun()
+          ->run(); // now we can run it again
+```
+
+Another handy method if you are re-using the same instance of the scheduler with different jobs (e.g. job coming from an external source - db, file ...) on every run, is to clear the current scheduled jobs.
+```php
+$scheduler->clearJobs()
+          ->resetRun()
+          ->run(); // now we can run it again
+```
+
+### Faking scheduler run time
+When running the scheduler you might pass an `DateTime` to fake the scheduler run time.
+The resons for this feature are described [here](https://github.com/peppeocchi/php-cron-scheduler/pull/28);
+
+```
+// ...
+$fakeRunTime = new DateTime('2017-09-13 00:00:00');
+$scheduler->run($fakeRunTime);
+```

src/GO/Job.php

@@ -81,6 +81,13 @@ class Job
      */
     private $output;
 
+    /**
+     * The return code of the executed job.
+     *
+     * @var int
+     */
+    private $returnCode = 0;
+
     /**
      * Files to write the output of the job.
      *
@@ -361,7 +368,7 @@ public function run()
         if (is_callable($compiled)) {
             $this->output = $this->exec($compiled);
         } else {
-            $this->output = exec($compiled);
+            exec($compiled, $this->output, $this->returnCode);
         }
 
         $this->finalise();
@@ -492,7 +499,7 @@ private function finalise()
 
         // Call any callback defined
         if (is_callable($this->after)) {
-            call_user_func($this->after, $this->output);
+            call_user_func($this->after, $this->output, $this->returnCode);
         }
     }
 

src/GO/Scheduler.php

@@ -149,14 +149,19 @@ public function raw($command, $args = [], $id = null)
     /**
      * Run the scheduler.
      *
+     * @param  DateTime  $runTime  Optional, run at specific moment
      * @return array  Executed jobs
      */
-    public function run()
+    public function run(Datetime $runTime = null)
     {
         $jobs = $this->getQueuedJobs();
 
+        if (is_null($runTime)) {
+            $runTime = new DateTime('now');
+        }
+
         foreach ($jobs as $job) {
-            if ($job->isDue()) {
+            if ($job->isDue($runTime)) {
                 try {
                     $job->run();
                     $this->pushExecutedJob($job);
@@ -169,6 +174,21 @@ public function run()
         return $this->getExecutedJobs();
     }
 
+    /**
+     * Reset all collected data of last run.
+     *
+     * Call before run() if you call run() multiple times.
+     */
+    public function resetRun()
+    {
+        // Reset collected data of last run
+        $this->executedJobs = [];
+        $this->failedJobs = [];
+        $this->outputSchedule = [];
+
+        return $this;
+    }
+
     /**
      * Add an entry to the scheduler verbose output array.
      *
@@ -268,4 +288,14 @@ public function getVerboseOutput($type = 'text')
                 throw new InvalidArgumentException('Invalid output type');
         }
     }
+
+    /**
+     * Remove all queued Jobs.
+     */
+    public function clearJobs()
+    {
+        $this->jobs = [];
+
+        return $this;
+    }
 }

tests/GO/JobTest.php

@@ -25,9 +25,6 @@ public function testShouldGenerateIdFromSignature()
         $this->assertNotEquals($job1->getId(), $job2->getId());
     }
 
-// Test scheduler: test that you schedule a job at one time, then wait 1 minute
-// and check that the Job still needs to be executed
-
     public function testShouldAllowCustomId()
     {
         $job = new Job('ls', [], 'aCustomId');
@@ -353,7 +350,7 @@ public function testShouldReturnOutputOfJobExecution()
         $command = PHP_BINARY . ' ' . __DIR__ . '/../test_job.php';
         $job3 = new Job($command);
         $job3->inForeground()->run();
-        $this->assertEquals('hi', $job3->getOutput());
+        $this->assertEquals(['hi'], $job3->getOutput());
     }
 
     public function testShouldRunCallbackAfterJobExecution()
@@ -392,6 +389,26 @@ public function testShouldRunCallbackAfterJobExecution()
             $job2Result === $job2->getOutput());
     }
 
+    public function testThenMethodShouldPassReturnCode()
+    {
+        $command_success = PHP_BINARY . ' ' . __DIR__ . '/../test_job.php';
+        $command_fail = $command_success . ' fail';
+
+        $run = function ($command) {
+            $job = new Job($command);
+            $testReturnCode = null;
+
+            $job->then(function ($output, $returnCode) use (&$testReturnCode, &$testOutput) {
+                $testReturnCode = $returnCode;
+            })->run();
+
+            return $testReturnCode;
+        };
+
+        $this->assertEquals(0, $run($command_success));
+        $this->assertNotEquals(0, $run($command_fail));
+    }
+
     public function testThenMethodShouldBeChainable()
     {
         $job = new Job('ls');

tests/GO/SchedulerTest.php

@@ -1,5 +1,6 @@
 <?php namespace GO\Job\Tests;
 
+use DateTime;
 use GO\Scheduler;
 use PHPUnit\Framework\TestCase;
 
@@ -252,4 +253,70 @@ public function testShouldPrioritizeJobsInBackround()
         $this->assertEquals('async_background', $jobs[0]->getId());
         $this->assertEquals('async_foreground', $jobs[1]->getId());
     }
+
+    public function testCouldRunTwice()
+    {
+        $scheduler = new Scheduler();
+
+        $scheduler->call(function () {
+            return true;
+        });
+
+        $scheduler->run();
+
+        $this->assertCount(1, $scheduler->getExecutedJobs(), 'Number of executed jobs');
+
+        $scheduler->resetRun();
+        $scheduler->run();
+
+        $this->assertCount(1, $scheduler->getExecutedJobs(), 'Number of executed jobs');
+    }
+
+    public function testClearJobs()
+    {
+        $scheduler = new Scheduler();
+
+        $scheduler->call(function () {
+            return true;
+        });
+
+        $this->assertCount(1, $scheduler->getQueuedJobs(), 'Number of queued jobs');
+
+        $scheduler->clearJobs();
+
+        $this->assertCount(0, $scheduler->getQueuedJobs(), 'Number of queued jobs');
+    }
+
+    public function testShouldRunDelayedJobsIfDueWhenCreated()
+    {
+        $scheduler = new Scheduler();
+        $currentTime = date('H:i');
+
+        $scheduler->call(function () {
+            $s = (int) date('s');
+            sleep(60 - $s + 1);
+        })->daily($currentTime);
+
+        $scheduler->call(function () {
+            // do nothing
+        })->daily($currentTime);
+
+        $executed = $scheduler->run();
+
+        $this->assertEquals(2, count($executed));
+    }
+
+    public function testShouldRunAtSpecificTime()
+    {
+        $scheduler = new Scheduler();
+        $runTime = new DateTime('2017-09-13 00:00:00');
+
+        $scheduler->call(function () {
+            // do nothing
+        })->daily('00:00');
+
+        $executed = $scheduler->run($runTime);
+
+        $this->assertEquals(1, count($executed));
+    }
 }

tests/test_job.php

@@ -1,3 +1,7 @@
 <?php
 
 echo 'hi';
+
+if (in_array('fail', $argv)) {
+    exit(1);
+}