Download the PHP package deploy-dog/slavedriver without Composer

Slavedriver

A PHP based cron job runner. Manage, monitor, log and react to problems with your scheduled tasks. Created by the team at deploy.dog initially for internal use, but modified and released for other to enjoy too. Created by deploy.dog initially for internal use, but released for others to enjoy too.

Requirements

• PHP 5.6, 7.0, 7.1 or HHVM
• Unix based OS such as Linux, FreeBSD or MacOS (Windows is not supported at this time)

Installation (via Composer obviously)

Usage

Create your file which describes your jobs.

We suggest using a file named slavedriver.php in the project root, and that's what we'll be using in this example.

A more detailed example of this file can be seen here, but the basics are below

Running Slavedriver

You need to get something (e.g. the real system crontab) to run your Slavedriver file every 1 minute (this time internal is important, don't change it).

Events

Events are dispatched throughout the process which you can listen to. You can use any PSR-14 (Event Manager) compatible event manager. PSR-14 is currently at the "proposed" stage so we should expect it to change. We'd recommend using phossa2/event as your PSR-14 event manager if you don't have one currently and don't want to implement your own. As PSR-14 is not out yet, we require a class which implements Phossa2\Event\Interfaces\EventManagerInterface so if you don't want to use phossa2/event you can write something else which implements that same class. Not ideal, I know, and we expect to change this in v2 when PSR-14 is approved.

You can listen to the follow events to monitor your Slavedriver jobs and act accordingly.

Hint: Use the Job's CustomData if you want to pass through additional data, such as whether to wake people up in the night if the job fails!

Catching events

Handling specific events

Handling all Slavedriver events

Slavedriver itself started (should be roughly every 1 minute)

• Event: slavedriver.started
• Event constant: Slavedriver::EVENT_SLAVEDRIVER_STARTED
• Event target: None
• Event params: None

Job started

• Event: slavedriver.job.started
• Event constant: Slavedriver::EVENT_JOB_STARTED
• Event target: The Job object
• Event params: None

Job finished successfully

• Event: slavedriver.job.finished.success
• Event constant: Slavedriver::EVENT_JOB_FINISHED_SUCCESS
• Event target: The Job object
• Event params: None

Job finished with error (based on exit code)

• Event: slavedriver.job.finished.error
• Event constant: Slavedriver::EVENT_JOB_FINISHED_ERROR
• Event target: The Job object
• Event params:
  • exitCode = The exit code of the command

Job stdOut data (this is called every few seconds with additional data)

• Event: slavedriver.job.output.stdout
• Event constant: Slavedriver::EVENT_JOB_OUTPUT_STDOUT
• Event target: The Job object
• Event params:
  • stdOut = The stdOut data since the last trigger of this event

Job stdErr data (this is called every few seconds with additional data)

• Event: slavedriver.job.output.stderr
• Event constant: Slavedriver::EVENT_JOB_OUTPUT_STDERR
• Event target: The Job object
• Event params:
  • stdErr = The stdErr data since the last trigger of this event

Job was still running when the timeout value was hit (and it will have been killed)

• Event: slavedriver.job.timeout
• Event constant: Slavedriver::EVENT_JOB_TIMEOUT
• Event target: The Job object
• Event params: None

Job should have been started but the last instance was still running and they cannot overlap

• Event: slavedriver.job.last_instance_still_running
• Event constant: Slavedriver::EVENT_JOB_LAST_INSTANCE_STILL_RUNNING
• Event target: The Job object
• Event params: None

Job still running but expected runtime has elapsed (job not killed)

• Event: slavedriver.job.expected_runtime_elapsed
• Event constant: Slavedriver::EVENT_JOB_EXPECTED_RUNTIME_ELAPSED
• Event target: The Job object
• Event params: None

Logging

Logging is provided by any PSR-3 compatible logger. You can provider custom log levels for different messages if you wish, or leave the leave the log levels at the defaults which are sensible. To setup logging, call the setLogger() method on the Slavedriver object, passing in the PSR-3 logger and optionally the log levels.

Or with custom log levels (e.g. override the ErrorExitCode log level to alert)

Exceptions

All exceptions thrown by Slavedriver extend the base Slavedriver exception deploydog\Slavedriver\Exception\Slavedriver which extends the base PHP exception \Exception. Different Slavedriver exceptions are thrown for different reasons, for example InvalidJob and InvalidSlavedriverConfig. Check the Exceptions directory for the possible options.