Feature add psr3 support (#4)

* Adding Psr\Logger support

* add documentation

* small documentation fix

Author: carstenwindler

README.md

@@ -149,6 +149,37 @@ If you want to send the output to an email address, you need to send first the o
 You can pass an array of files or emails if you want to send the output to multiple files/emails
 -> `output(['first_file', 'second_file'])->email(['myemail1' => 'Dev1', 'myemail2' => 'Dev2'])`
 
+### Advanced logging
+Additionally to the file or email output, you can use a PSR-3 compatible Logger (e.g. Monolog) to handle the job output.
+
+```php
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use GO\Scheduler;
+use Monolog\Logger;
+use Monolog\Handler\StreamHandler;
+
+$log = new Logger('logger-name');
+$log->pushHandler(new StreamHandler('/tmp/log.log', Logger::INFO));
+
+$scheduler
+    ->call(function () {
+        return "just output something";
+    })
+    ->at('* * * * *')
+    ->setLogger($log);
+
+$scheduler->run();
+```
+
+The Scheduler will use the INFO level for logging the output.
+
+#### More logging options
+- `->setLabel('my-log-label')` will log the job output using this label
+- `->setJobDoneMessage('job xyz done!')` will add an additional message that will be logged when the job is done. This can be useful if you want to track that a job is executed, even though it does not output anything by itself.  
+
 ### Conditional
 You can delegate the execution of a cronjob to a truthful test.
 ```

composer.json

@@ -7,13 +7,20 @@
         {
             "name": "Giuseppe Occhipinti",
             "email": "peppeocchi@gmail.com"
+        },
+        {
+            "name": "Carsten Windler",
+            "email": "carsten@carstenwindler.de",
+            "homepage": "http://carstenwindler.de",
+            "role": "Contributor"
         }
     ],
     "minimum-stability": "dev",
     "require": {
         "php": ">=5.5.9",
         "mtdowling/cron-expression": "@stable",
-        "swiftmailer/swiftmailer": "@stable"
+        "swiftmailer/swiftmailer": "@stable",
+        "psr/log": "~1.0"
     },
     "require-dev": {
         "phpunit/phpunit": "5.0.*"

src/GO/Job/Job.php

@@ -4,12 +4,14 @@
 use GO\Services\Interval;
 
 use Cron\CronExpression;
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerInterface;
 use Swift_Attachment;
 use Swift_Mailer;
 use Swift_MailTransport;
 use Swift_Message;
 
-abstract class Job
+abstract class Job implements LoggerAwareInterface
 {
   /**
    * The command
@@ -80,7 +82,24 @@ abstract class Job
    * @var bool
    */
   public $truthTest = true;
+  
+  /**
+   * PSR-3 compliant logger
+   * @var \Psr\Log\LoggerInterface
+   */
+  private $logger;
+
+  /**
+   * Label for the job, to make it easier to identify in the logs
+   * @var string
+   */
+  private $jobLabel;
 
+  /**
+   * Optional message that will be added to the
+   * @var string
+   */
+  private $jobDoneMessage;
 
   /**
    * Create a new instance of Job
@@ -237,7 +256,11 @@ protected function compile($command)
       }
     }
 
-    $command .= ' > /dev/null 2>&1';
+    // Only hide output if no loggers are used
+    if (!$this->logger) {
+      $command .= ' > /dev/null 2>&1';
+    }
+
     if ($this->runInBackground === true) {
       $command .= ' &';
     }
@@ -252,16 +275,23 @@ protected function compile($command)
    */
   public function exec()
   {
+    $jobOutput = [];
     $this->compiled = $this->build();
     if (is_callable($this->compiled)) {
       $return = call_user_func($this->command, $this->args);
       foreach ($this->outputs as $output) {
         Filesystem::write($return, $output, $this->mode);
       }
+
+      if (is_string($return)) {
+        $jobOutput[] = $return;
+      }
     } else {
-      $return = exec($this->compiled);
+      $return = exec($this->compiled, $jobOutput);
     }
 
+    $this->logJobOutput($jobOutput);
+
     if ($this->emails) {
       $this->sendEmails();
     }
@@ -329,4 +359,73 @@ public function when($test)
 
     return $this;
   }
+
+  /**
+   * Attach a PSR-3 compliant logger to this job
+   *
+   * @param \Psr\Log\LoggerInterface $logger
+   *
+   * @return $this
+   */
+  public function setLogger(LoggerInterface $logger)
+  {
+    $this->logger = $logger;
+
+    return $this;
+  }
+
+  /**
+   * Define a label for this job, which is used by the logger
+   *
+   * @param string $label
+   *
+   * @return $this
+   */
+  public function setLabel($label)
+  {
+    $this->jobLabel = $label;
+
+    return $this;
+  }
+
+  /**
+   * Define a message that will be logged after the job has run
+   *
+   * @param string $message
+   *
+   * @return $this
+   */
+  public function setJobDoneMessage($message)
+  {
+    $this->jobDoneMessage = $message;
+
+    return $this;
+  }
+
+  /**
+   * Get the log label for this job
+   * @return string
+   */
+  protected function getLogLabel()
+  {
+    return (!empty($this->jobLabel)) ? $this->jobLabel : '';
+  }
+
+  /**
+   * Log output, if there is anything to log
+   *
+   * @param array $jobOutput
+   *
+   * @return void
+   */
+  protected function logJobOutput($jobOutput)
+  {
+    if (count($jobOutput) > 0) {
+      $this->logger->info($this->getLogLabel(), $jobOutput);
+    }
+
+    if ($this->jobDoneMessage !== null) {
+      $this->logger->info($this->getLogLabel(), [ $this->jobDoneMessage ]);
+    }
+  }
 }

tests/GO/Job/LoggerTest.php

@@ -0,0 +1,112 @@
+<?php namespace GO\Job\Tests;
+
+use GO\Job\JobFactory;
+
+class JobMock extends \GO\Job\Job
+{
+    public function build()
+    {
+        return "dude";
+    }
+}
+
+class LoggerTest extends \PHPUnit_Framework_TestCase
+{
+    private function isWindows()
+    {
+        return (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN');
+    }
+
+    private function getPsrLoggerMock()
+    {
+        return $this
+            ->getMockBuilder('Psr\Log\LoggerInterface')
+            ->setMethods([ 'emergency', 'alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug', 'log' ])
+            ->getMock();
+    }
+
+    public function testShouldNotSendOutputToDevNullIfLoggerIsAttached()
+    {
+        $job = JobFactory::factory('GO\Job\Raw', 'somecommand');
+
+        $loggerMock = $this->getMock('Psr\Log\LoggerInterface');
+
+        $job->setLogger($loggerMock);
+
+        $this->assertEquals('somecommand &', $job->build());
+    }
+
+    public function testShouldLogShellOutput()
+    {
+        if ($this->isWindows()) {
+            $this->markTestSkipped("Can't execute shell script on Windows");
+        }
+
+        $job = JobFactory::factory('GO\Job\Raw', __DIR__ . '/../../test_job.sh');
+
+        $loggerMock = $this->getPsrLoggerMock();
+        $loggerMock
+            ->expects($this->once())
+            ->method('info')
+            ->with('', [ 'testoutput1', 'testoutput2' ]);
+        
+        $job->setLogger($loggerMock);
+
+        $job->exec();
+    }
+
+    public function testShouldLogClosureOutput()
+    {
+        $job = JobFactory::factory('GO\Job\Closure', function () {
+            return "closureoutput";
+        });
+
+        $loggerMock = $this->getPsrLoggerMock();
+        $loggerMock
+            ->expects($this->once())
+            ->method('info')
+            ->with('', [ 'closureoutput' ]);
+
+        $job->setLogger($loggerMock);
+
+        $job->exec();
+    }
+
+    public function testShouldLogLabelIfSet()
+    {
+        $job = JobFactory::factory('GO\Job\Closure', function () {
+            return "closureoutput";
+        });
+        
+        $loggerMock = $this->getPsrLoggerMock();
+        $loggerMock
+            ->expects($this->once())
+            ->method('info')
+            ->with('mylabel', [ 'closureoutput' ]);
+
+        $job->setLabel('mylabel')->setLogger($loggerMock);
+
+        $job->exec();
+    }
+
+    public function testShouldLogJobDoneMessage()
+    {
+        $job = JobFactory::factory('GO\Job\Closure', function () {
+            return "closureoutput";
+        });
+
+        $loggerMock = $this->getPsrLoggerMock();
+        $loggerMock
+            ->expects($this->at(0))
+            ->method('info')
+            ->with('', [ 'closureoutput' ]);
+        $loggerMock
+            ->expects($this->at(1))
+            ->method('info')
+            ->with('', [ 'job done' ]);
+
+        $job->setJobDoneMessage('job done')->setLogger($loggerMock);
+
+        $job->exec();
+    }
+}

tests/test_job.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+echo "testoutput1"
+echo "testoutput2"