Repo no longer maintained, please use Crunz from new repo: https://github.com/crunzphp/crunz - more info here: https://github.com/lavary/crunz/issues/411

Crunz

Install a cron job once and for all, manage the rest from the code.

Crunz is a framework-agnostic package to schedule periodic tasks (cron jobs) in PHP using a fluent API.

Crunz is capable of executing any kind of executable command as well as PHP closures.

|Version|Supported PHP versions |---|---| |dev v3 (v3.2-dev)| |stable v3 (v3.1.0)| |stable v2 (v2.3.1)| |stable v1 (v1.12.4)|

Roadmap

|Version|Release date|Active support until|Bug support until|Status |---|---|---|---|---| |v1.x|April 2016|April 2019|April 2020|End of life |v2.x|April 2019|April 2021|April 2022|Bug support |v3.x|April 2021|April 2023|April 2024|Active support

Installation

To install it:

composer require lavary/crunz

If the installation is successful, a command-line utility named crunz is symlinked to the vendor/bin directory of your project.

How It Works?

The idea is very simple: instead of installing cron jobs in a crontab file, we define them in one or several PHP files, by using the Crunz interface.

Here's a basic example:

<?php
// tasks/backupTasks.php

use Crunz\Schedule;

$schedule = new Schedule();
$task = $schedule->run('cp project project-bk');       
$task->daily();

return $schedule;

To run the tasks, you only need to install an ordinary cron job (a crontab entry) which runs every minute, and delegates the responsibility to Crunz' event runner:

* * * * * cd /project && vendor/bin/crunz schedule:run

The command schedule:run is responsible for collecting all the PHP task files and run the tasks which are due.

Task Files

Task files resemble crontab files. Just like crontab files they can contain one or more tasks.

Normally we create our task files in the tasks/ directory within the project's root directory.

By default, Crunz assumes all the task files reside in the tasks/ directory within the project's root directory.

There are two ways to specify the source directory: 1) Configuration file 2) As a parameter to the event runner command.

We can explicitly set the source path by passing it to the event runner as a parameter:

* * * * * cd /project && vendor/bin/crunz schedule:run /path/to/tasks/directory

Creating a Simple Task

In the terminal, change the directory to your project's root directory and run the following commands:

mkdir tasks && cd tasks
nano GeneralTasks.php

Then, add a task as below:

<?php
// tasks/FirstTasks.php

use Crunz\Schedule;

$schedule = new Schedule();

$task = $schedule->run('cp project project-bk'); 
$task
    ->daily()
    ->description('Create a backup of the project directory.');

// ...

// IMPORTANT: You must return the schedule object
return $schedule; 

There are some conventions for creating a task file, which you need to follow. First of all, the filename should end with Tasks.php unless we change this via the configuration settings.

In addition to that, we must return the instance of Schedule class at the end of each file, otherwise, all the tasks inside the file will be skipped by the event runner.

Since Crunz scans the tasks directory recursively, we can either put all the tasks in one file or across different files (or directories) based on their usage. This behavior helps us have a well organized tasks directory.

The Command

We can run any command or script by using run(). This method accepts two arguments: the command to be executed, and the command options (as an associative array) if there's any.

Normal Command or Script

<?php

use Crunz\Schedule;

$schedule = new Schedule();
$task = $schedule->run(PHP_BINARY . ' backup.php', ['--destination' => 'path/to/destination']);
$task
    ->everyMinute()
    ->description('Copying the project directory');

return $schedule;

In the above example, --destination is an option supported by backup.php script.

Closures

We can also write to a closure instead of a command:

<?php

use Crunz\Schedule;

$schedule = new Schedule();

$x = 12;
$task = $schedule->run(function() use ($x) { 
   // Do some cool stuff in here 
});

$task
    ->everyMinute()
    ->description('Copying the project directory');

return $schedule;

Frequency of Execution

There are a variety of ways to specify when and how often a task should run. We can combine these methods together to get our desired frequencies.

Units of Time

There are a group of methods which specify a unit of time (bigger than minute) as frequency. They usually end with ly suffix, as in hourly(), daily(), weekly, monthly(), quarterly(), and yearly .

All the events scheduled with this set of methods happen at the beginning of that time unit. For example weekly() will run the event on Sundays, and monthly() will run on the first day of each month.

The task below will run daily at midnight (start of the daily time period).

<?php
// ...
$task = $schedule->run(PHP_BINARY . ' backup.php');    
$task->daily();
// ...

Here's another one, which runs on the first day of each month.

<?php
// ...
$task = $schedule->run(PHP_BINARY . ' email.php');
$task->monthly();
// ...

Running Events at Certain Times

To schedule a one-off tasks, you may use on() method like this:

<?php
// ...
$task = $schedule->run(PHP_BINARY . ' email.php'); 
$task->on('13:30 2016-03-01');
// ...

The above task will run on the first of march 2016 at 01:30 pm.

On() accepts any date format parsed by PHP's strtotime function.

To specify the time of a task we use at() method:

<?php
// ...
$task = $schedule->run(PHP_BINARY . ' email.php'); 
$task
    ->daily()
    ->at('13:30');
// ...

If we only pass a time to the on() method, it will have the same effect as using at()

<?php
// ...
$task = $schedule->run(PHP_BINARY . ' email.php');   
$task
    ->daily()
    ->on('13:30');
         
// is the sames as
$task = $schedule->run(PHP_BINARY . ' email.php');       
$task
    ->daily()
    ->at('13:30');
// ...

We can combine the "Unit of Time" methods eg. daily(), monthly() with the at() or on() constraint in a single statement if we wish.

The following task will be run every hour at the 15th minute

<?php
// ...
$task = $schedule->run(PHP_BINARY . ' feedmecookie.php'); 
$task
    ->hourlyAt('15');
// ...

hourlyOn('15') could have been used instead of hourlyAt('15') with the same result

The following task will be run Monday at 13:30

<?php
// ...
$task = $schedule->run(PHP_BINARY . ' startofwork.php'); 
$task
    ->weeklyOn(1,'13:30');
// ...

Sunday is considered day 0 of the week.

If we wished for the task to run on Tuesday (day 2 of the week) at 09:00 we would have used:

<?php
// ...
$task = $schedule->run(PHP_BINARY . ' startofwork.php'); 
$task
    ->weeklyOn(2,'09:00');
// ...

Task Life Time

In a crontab entry, we can not easily specify a task's lifetime (the period of time when the task is active). However, it's been made easy in Crunz:

<?php
//
$task = $schedule->run(PHP_BINARY . ' email.php');
$task
    ->everyFiveMinutes()
    ->from('12:30 2016-03-04')
    ->to('04:55 2016-03-10');
 //       

Or alternatively we can use the between() method to accomplish the same result:

<?php
//
$task = $schedule->run(PHP_BINARY . ' email.php');
$task
    ->everyFiveMinutes()
    ->between('12:30 2016-03-04', '04:55 2016-03-10');

 //       

If we don't specify the date portion, the task will be active every day but only within the specified duration:

<?php
//
$task = $schedule->run(PHP_BINARY . ' email.php');
$task
     ->everyFiveMinutes()
     ->between('12:30', '04:55');

 //       

The above task runs every five minutes between 12:30 pm and 4:55 pm every day.

An example of restricting a task from running only during a certain range of minutes each hour can be achieved as follows:

<?php
//

$hour = date('H');
$startminute = $hour.':05';
$endminute = $hour.':15';

$task = $schedule->run(PHP_BINARY . ' email.php');
$task
     ->hourly()
     ->between($startminute, $endminute);

 //       

The above task runs every hour between minutes 5 to 15

Weekdays

Crunz also provides a set of methods which specify a certain day in the week.

• mondays()
• tuesdays()
• ...
• sundays()
• weekedays()
• weekends()

These methods have been designed to be used as a constraint and should not be used alone. The reason is that weekday methods just modify the Day of Week field of a cron job expression.

Consider the following example:

<?php
// Cron equivalent:  * * * * 1
$task = $schedule->run(PHP_BINARY . ' startofwork.php');
$task->mondays();

At first glance, the task seems to run every Monday, but since it only modifies the "day of week" field of the cron job expression, the task runs **ev