jobby

Open source

Manage all your cron jobs without modifying crontab. Handles locking, logging, error emails, and more.

1.0K stars0 likes0 views

About

Manage all your cron jobs without modifying crontab. Handles locking, logging, error emails, and more.

Jobby, a PHP cron job manager

Install the master jobby cron job, and it will manage all your offline tasks. Add jobs without modifying crontab. Jobby can handle logging, locking, error emails and more.

NEW REPO: We have moved jobby to a Github org. Please update your remotes to https://github.com/jobbyphp/jobby.git.

Features

Maintain one master crontab job.
Jobs run via PHP, so you can run them under any programmatic conditions.
Use ordinary crontab schedule syntax (powered by the excellent cron-expression).
Run only one copy of a job at a given time.
Send email whenever a job exits with an error status.
Run job as another user, if crontab user has sudo privileges.
Run only on certain hostnames (handy in webfarms).
Theoretical Windows support (but not ever tested)

Getting Started

Installation

The recommended way to install Jobby is through Composer:

$ composer require hellogerard/jobby

Then add the following line to your (or whomever's) crontab:

* * * * * cd /path/to/project && php jobby.php 1>> /dev/null 2>&1

After Jobby installs, you can copy an example file to the project root.

$ cp vendor/hellogerard/jobby/resources/jobby.php .

Running a job

php

add('CommandExample', [

    // Run a shell command
    'command'  => 'ls',

    // Ordinary crontab schedule format is supported.
    // This schedule runs every hour.
    'schedule' => '0 * * * *',

]);

$jobby->run();

Examples

Logging

php

add('LoggingExample', [
    
    'command' => 'ls',
    'schedule' => '0 * * * *',
    
    // Stdout and stderr is sent to the specified file
    'output' => 'logs/command.log',

]);

/* ... */

Disabling a command

php

add('DisabledExample', [
    
    'command' => 'ls',
    'schedule' => '0 * * * *',
    
    // You can turn off a job by setting 'enabled' to false
    'enabled' => false,

]);

/* ... */

Running closures

When running closures, beware that nothing outside of the closure is visible (see #93)!

php

add('ClosureCommandExample', [
    
     // Use the 'closure' key
     // instead of 'command'
    'closure' => function() {
        echo "I'm a function!\n";
        return true;
    },
    
    'schedule' => '0 * * * *',

]);

/* ... */

Using a DateTime

php

add('DateTimeExample', [
    
    'command' => 'ls',
    
    // Use a DateTime string in
    // the format Y-m-d H:i:s
    'schedule' => '2017-05-03 17:15:00',

]);

/* ... */

Using a Custom Scheduler

php

add('Example', [
    
    'command' => 'ls',
    
    // Use any callable that returns
    // a boolean stating whether
    // to run the job or not
    'schedule' => function(DateTimeImmutable $now) {
        // Run on even minutes
        return $now->format('i') % 2 === 0;
    },

]);

/* ... */

Supported Options

Each job requires these:

Key	Type	Description
schedule	string	Crontab schedule format (`man -s 5 crontab`) or DateTime format (`Y-m-d H:i:s`) or callable (`function(): Bool { /* ... */ }`)
command	string	The shell command to run (exclusive-or with `closure`)
closure	Closure	The anonymous PHP function to run (exclusive-or with `command`)

The options listed below can be applied to an individual job or globally through the Jobby constructor. Global options will be used as default values, and individual jobs can override them.

Option	Type	Default	Description
runAs	string	null	Run as this user, if crontab user has `sudo` privileges
debug	boolean	false	Send `jobby` internal messages to 'debug.log'
Filtering			Options to determine whether the job should run or not
environment	string	null or `getenv('APPLICATION_ENV')`	Development environment for this job
runOnHost	string	`gethostname()`	Run jobs only on this hostname
maxRuntime	integer	null	Maximum execution time for this job (in seconds)
enabled	boolean	true	Run this job at scheduled times
haltDir	string	null	A job will not run if this directory contains a file bearing the job's name
Logging			Options for logging
output	string	/dev/null	Redirect `stdout` and `stderr` to this file
output_stdout	string	value from `output` option	Redirect `stdout` to this file
output_stderr	string	value from `output` option	Redirect `stderr` to this file
dateFormat	string	Y-m-d H:i:s	Format for dates on `jobby` log messages
Mailing			Options for emailing errors
recipients	string	null	Comma-separated string of email addresses
mailer	string	sendmail	Email method: sendmail or smtp or mail
smtpHost	string	null	SMTP host, if `mailer` is smtp
smtpPort	integer	25	SMTP port, if `mailer` is smtp
smtpUsername	string	null	SMTP user, if `mailer` is smtp
smtpPassword	string	null	SMTP password, if `mailer` is smtp
smtpSecurity	string	null	SMTP security option: ssl or tls, if `mailer` is smtp
smtpSender	string	jobby@<hostname>	The sender and from addresses used in SMTP notices
smtpSenderName	string	Jobby	The name used in the from field for SMTP messages