Batch Jobs

With batch jobs you can run tasks repeatedly without manual invocation. Batch jobs can be called by Crontabs.

Registering a Batch Job​

You can use any class as a batch job that is marked as "lookupable". In the following example we create a batch job in the package atusch\batch:

<?php
namespace atusch\batch;

use n2n\context\Lookupable;

class ExampleBatchJob implements Lookupable {

    public function _onNewHour() {
        echo 'one hour passed';
    }
}

In batch job classes you can implement certain callback methods, which are executed with a different frequency depending on their name. In the example above the method _onNewHour() is executed once per hour.

Batch jobs must be registered in the app.ini under the group [general].

[general]

application.batch_jobs[] = "atusch\batch\ExampleBatchJob"

Setting Up Batch Jobs​

In a standard n2n installation you will find the instruction n2n\N2N::autoInvokeBatchJobs(); in the script public/index.php. Your batch jobs are triggered by this instruction, i.e. all callback methods that are eligible for execution at the current time are executed. If you leave n2n\N2N::autoInvokeBatchJobs(); in public/index.php, this means that batch jobs could also be executed during every page request (public/index.php is executed on every page request). If your batch job takes a while, your users have to accept a correspondingly longer request time from time to time when calling a page.

Furthermore, you make the frequency with which your batch jobs are called dependent on the behavior of the users. If, as in the example above, you have registered a batch job with an _onNewHour() method and there are no page requests from users for 3 hours, this method will never be executed during these 3 hours either, because n2n\N2N::autoInvokeBatchJobs(); was never called during that time.

To make your batch jobs somewhat more predictable, it is worth moving n2n\N2N::autoInvokeBatchJobs(); into a separate script (e.g. batch.php). This script could look like this:

<?php
$pubPath = realpath(dirname(__FILE__));
$appPath = realpath($pubPath . '/../app');
$n2nPath = realpath($pubPath . '/../lib');
$varPath = realpath($pubPath . '/../var');

set_include_path(implode(PATH_SEPARATOR, array($appPath, $n2nPath, get_include_path())));

if (isset($_SERVER['N2N_STAGE'])) {
    define('N2N_STAGE', $_SERVER['N2N_STAGE']);
}

require_once 'n2n/N2N.php';

n2n\N2N::setup($pubPath, $varPath);
n2n\N2N::initialize(new n2n\core\FileN2nCache());

n2n\N2N::autoInvokeBatchJobs();

n2n\N2N::finalize();

You can now set up a Crontab that calls this script as often as you like. Of course, you also have to choose a suitable frequency here. If you have registered a batch job with the callback method _onNewHour(), the script must also be called at least once per hour to make sure that _onNewHour() is really executed every hour.

If you want your batch jobs to be called in an HTTP context, wget is suitable as a Crontab instruction.

wget -O /dev/null https://www.example.com/batch.php

Attention

Remember to delete n2n\N2N::autoInvokeBatchJobs(); from public/index.php if you have set up a separate batch script.

Callback Methods​

All callback methods in batch jobs are magic and can have any visibility. If the batch job is triggered manually or by the system, the _onTrigger() callback method is always executed first. By defining a parameter of type DateTime you can also have the time at which the respective method was last executed passed to you.

The following methods are called with a predefined frequency:

<?php
namespace atusch\batch;

use n2n\model\Lookupable;

class ExampleBatchJob implements Lookupable {

    public function _onTrigger() {
        // gets called every time the batch job is triggered
    }

    public function _onNewHour(\DateTime $lastTriggered) {
        // gets called on every new hour
    }

    public function _onNewDay() {
        // gets called on every new day
    }

    public function _onNewWeek() {
        // gets called on every new week
    }

    public function _onNewMonth() {
        // gets called on every new month
    }

    public function _onNewYear() {
        // gets called on every new year
    }
}

All callback methods with the prefix "_onNew" are executed as soon as the corresponding time unit of the current time differs from the time at which the callback method was last executed. For example, if _onNewHour() is executed at 4:45 pm, it can be executed again at 5:00 pm, because the time unit "Hour" has changed.

Via the annotation n2n\batch\AnnoBatch you can also define your own callback methods. n2n\batch\AnnoBatch expects a \DateInterval as parameter, which corresponds to the frequency with which your callback method should be called.

<?php
namespace atusch\batch;

use n2n\model\Lookupable;
use n2n\batch\attribute\BatchInterval;

class ExampleBatchJob implements Lookupable {
    #[BatchInterval(new \DateInterval('PT15M'))]
    public function every15Min() {
        // gets called every 15 minutes
    }
}

In the example above the method every15Min() is executed every 15 minutes.