---
title: "Cron Job"
slug: "php-cron-job"
description: "Send logged PHP Library requests with a cron job: MappIntelligenceCronjob class or cronjob.php script, exit status, options and log file handling."
status: "update"
updated: 2026-11-02T16:56:32Z
published: 2026-11-02T16:56:32Z
canonical: "docs.mapp.com/php-cron-job"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cron Job

We recommend using a cron job to send logfile requests to the Mapp tracking server every few minutes and empty your file to keep it at a manageable size. You have two options:

## Custom Cron Job File

This option requires you to write your own cron job file and use our *MappIntelligenceCronjob* class.

#### Methods

#### constructor

For a complete configuration of the Mapp Intelligence Cronjob please check [Configuration](/v1/docs/php-integration-and-configuration).

```php
/**
 * @param MappIntelligenceConfig|array $config Config object or array of command line options
 * @throws MappIntelligenceCLIException Missing track ID / track domain or unsupported option
 */
$mappIntelligenceCronjob = new MappIntelligenceCronjob($config);
```

The constructor accepts:

- a `MappIntelligenceConfig` object (all configuration options), or
- an array with the options of the predefined cron job script (see below), as returned by `getopt()`: `trackId` / `i`, `trackDomain` / `d`, `consumerType` / `t`, `config` / `c`, `filename` / `f`, `filePath` / `f`, `filePrefix` / `p`, `logLevel` / `l`, `deactivate`, `debug`, `help` and `version`. Any other key (for example `maxAttempt`) throws an exception; set further options in the configuration file (`config`).

The exception class is `MappIntelligence\Cronjob\MappIntelligenceCLIException`. It is thrown if the track ID or the track domain is missing or an option is not supported. Every consumer type other than `FILE_ROTATION` is treated as `FILE`.

The cron job always sends with the consumer `CURL`, a batch size of 1000 requests (`maxBatchSize`), an unlimited queue (`maxQueueSize = 0`, so no request of a log file is discarded because the queue is full) and no `requestInterval`; the configured values of these options are not used. `maxAttempt`, `attemptTimeout`, `connectionTimeout`, `readTimeout` and `forceSSL` are used as configured.

#### run

Send the logfile requests to the Mapp tracking server and delete your logfiles to keep it at a mangeable size. Returns the following results:

- **0**: All data was sent successfully, there was nothing to send, the tracking is deactivated, another run of the cron job is still sending the files, or the help / version was printed.
- **1**: An error has occurred: requests could not be delivered and stay for the next run, a log file contained requests that can never be sent, a log file could not be read or removed, or the configuration / directory is invalid.

Every log file is sent with its own queue, the files are processed from the oldest to the newest. Depending on the result, the file is handled like this:

| Result | Log file |
| --- | --- |
| All requests were sent | Deleted. If it cannot be deleted, it is renamed to `*.sent` (WARN) and not sent again. |
| All requests were sent, but the file can neither be deleted nor renamed to `*.sent` | Kept (ERROR), this and all later files stay, exit status 1. The next run sends the file again, so its requests are delivered twice. |
| At least one batch can never be sent (e.g. HTTP 4xx because of a wrong track ID) | Its requests (only these, not the delivered ones) are appended to `*.discarded` (ERROR) and not sent again; the data stays on disk. If no request is left to retry, the file is deleted (or renamed to `*.sent`), the run continues with the next file, exit status 1. If requests are left to retry, the file keeps only them (see the next row). If the discarded requests cannot be written, the file stays unchanged (ERROR): this and all later files stay, exit status 1, and the next run sends the file again. |
| Requests could not be delivered right now (track server not reachable, HTTP 5xx, 408, 429) | Kept with the requests that were not delivered (logged at level INFO) and sent by the next run; this and all later files stay, exit status 1. Requests of batches that were discarded in the same run are kept in `*.discarded` (see above), not in the file. |
| The file cannot be read (no read permission, or a directory with the name of a log file) | Kept (ERROR), this and all later files stay, exit status 1. A directory named like a log file (`*.log` with `FILE_ROTATION`, `*.pending` with `FILE`) blocks every run until it is removed. |

A file that was sent partially keeps only the requests that were not delivered, so the next run does not send the delivered ones again. The file is replaced atomically: the remaining requests are written into a temporary file `<log file>.<random>.part` first, which then replaces the log file. If the replacement fails (ERROR) or the cron job is killed in the middle of a file, the whole file is sent again by the next run. A `*.part` file left by an aborted replacement is never cleaned up and never sent; it can be deleted, the log file still contains all of its requests. The log files belong to the cron job alone, the web servers only write into the request logging file (`FILE`) or the temporary files (`FILE_ROTATION`).

Only one run at a time sends the files: a run holds an exclusive lock (`flock`) on `<filename>.cronjob.lock` (`FILE`) or `<filePath><filePrefix>.cronjob.lock` (`FILE_ROTATION`). A run that starts while another one is still sending ends right away with exit status 0 and an INFO message. The lock is released by the operating system when the process ends, also if it is killed. If the lock file cannot be created (e.g. the directory does not exist or is not writable), the run sends without a lock, so overlapping runs are not prevented in that case.

With the file consumer type `FILE` the request logging file is taken over by renaming it into `<filename>.<timestamp>-<random>.pending` (the web server continues with a new file); an empty request logging file is not taken over. Every file named `<filename>.….pending` is sent, so an interrupted run is continued by the next one. If the request logging file cannot be taken over, the existing `*.pending` files are still sent and the exit status is 1.

With `FILE_ROTATION`, expired temporary files (configured `maxFileDuration`) are renamed into log files first. Only files named `<filePrefix>-<timestamp>…` are taken (temporary files `*.tmp` and log files `*.log`), so the prefix `Shop` takes neither the files of `ShopDE` nor those of `Shop-DE`.

The web server processes and the cron job are coordinated with exclusive file locks (`flock()`), so no request is written into a file while it is taken over.

```php
/**
 * @return int Status
 */
$mappIntelligenceCronjob->run();
```

##### Example

```php
use MappIntelligence\MappIntelligenceCronjob;
use MappIntelligence\Config\MappIntelligenceConfig;
use MappIntelligence\Consumer\MappIntelligenceConsumerType;

$status = 1;
try {
    $mappIntelligenceConfig = new MappIntelligenceConfig();
    $mappIntelligenceConfig->setTrackId("111111111111111")
        ->setTrackDomain("analytics01.wt-eu02.net")
        ->setConsumerType(MappIntelligenceConsumerType::FILE_ROTATION)
        ->setFilePath("/path/to/your/log/file/")
        ->setFilePrefix("MappIntelligenceData");

    $cronjob = new MappIntelligenceCronjob($mappIntelligenceConfig);

    $status = $cronjob->run();
} catch (Exception $e) {
    fwrite(STDERR, $e->getMessage() . PHP_EOL);
}

exit($status);
```

## Predefined Cron Job Script

This option allows you to use our predefined `cronjob.php` script, which is included in our repository

| Short notation | Long notation | Description |
| --- | --- | --- |
| -i | --trackId | Enter your Mapp Intelligence track ID provided by Mapp. |
| -d | --trackDomain | Enter your Mapp Intelligence tracking URL. |
| -t | --consumerType | Enter your current file consumer type. Options: "FILE", "FILE_ROTATION". Defaults to "FILE". |
| -c | --config | Enter the path to your configuration file (*.ini). |
|  |
| -f | --filename | Enter the path to your request logging file. Only relevant for file consumer type "FILE". Defaults to "/tmp/MappIntelligenceRequests.log". |
| -f | --filePath | Enter the path to your request logging files. Only relevant for file consumer type "FILE_ROTATION". Defaults to "/tmp/". The short form `-f` sets both `filename` and `filePath`. |
| -p | --filePrefix | Enter the prefix for your request logging files. Only relevant for file consumer type "FILE_ROTATION". Defaults to "MappIntelligenceRequests". |
|  |
| -l | --logLevel | Log level of the debug mode: "DEBUG", "INFO", "WARN", "ERROR", "FATAL" or "NONE". In an array of options, the former short form `ll` is still accepted. |
|  | --deactivate | Deactivate the tracking functionality. |
|  | --debug | Activates the debug mode. The debug mode sends messages to the command line. |
|  | --help | Display the help and exit (exit status 0, nothing is sent). |
|  | --version | Display version and exit (exit status 0, nothing is sent). |

The script loads the Composer autoloader of a standalone checkout (`./vendor/autoload.php`) or of the project it is installed in (`vendor/autoload.php`). Configuration errors are printed to STDERR.

##### Example

```bash
$ php cronjob.php -i 111111111111111 -d analytics01.wt-eu02.net -t FILE_ROTATION -f /tmp/ -p MappIntelligenceData
 
$ php cronjob.php -i 111111111111111 -d analytics01.wt-eu02.net -t FILE_ROTATION -f /tmp/ -p MappIntelligenceData --debug
 
 
$ php cronjob.php -c /path/to/your/configuration/file/config.ini
 
$ php cronjob.php -c /path/to/your/configuration/file/config.ini --debug
```

## Define a Cron Job

To create your crontab file, type the following command at the shell prompt `crontab -e` and add the following lines:

```bash
# sends every five minutes the tracking data to the Mapp tracking serve
*/5 * * * * php ./cronjob.php -c /path/to/your/configuration/file/config.ini
```