Sitellite Cookbook

Table of Contents

About Scheduler

Scheduler is exactly as its name suggests, a scheduler. It has the ability to run a series of tasks from the command-line, for the purpose of running them at specific intervals (ie. a nightly backup script).

Task Scripts

A script that is run by Scheduler is called a task. Tasks are simply PHP files, with only one required element, that live in the inc/app/scheduler/tasks folder. Each task is given its own sub-folder of the tasks folder, for example:

bash$ ls -al inc/app/scheduler/tasks
total 3
drwxrwxrwx   2 lux  staff  1024 Nov  3 12:23 documents
drwxrwxrwx   2 lux  staff  1024 Nov  3 12:23 jabbercheck
drwxrwxrwx   2 lux  staff  1024 Nov  3 12:23 mailcheck

Inside each folder, the task script is always named index.php.

The one required element that must be present in all tasks, for security reasons, is as follows:


<?php

// BEGIN CLI KEEPOUT CHECKING
if (php_sapi_name () !== 'cli') {
    // Add these lines to the very top of any file you don't want people to
    // be able to access directly.
    header ('HTTP/1.1 404 Not Found');
    echo "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n"
        . "<html><head>\n<title>404 Not Found</title>\n</head><body>\n<h1>Not Found</h1>\n"
        . "The requested URL " . $PHP_SELF . " was not found on this server.<p>\n<hr>\n"
        . $_SERVER['SERVER_SIGNATURE'] . "</body></html>";
    exit;
}
// END CLI KEEPOUT CHECKING

?>

This block ensures that if your task is called by any source but the command-line PHP interpreter, that it should fake a {{404 Not Found} error and exit. All of your task code then follows that block in your task file.

The Error Log

Because Scheduler is supposed to be called repeatedly at various intervals (ie. nightly, hourly, etc.) via your server's scheduling utility (cron, the Windows Task Scheduler), and not by an actual administrative user, it is intended to produce no output to the screen. So the rule is, no response is a good response, when it comes to Scheduler. A response on the screen means a task is not functioning correctly.

In fact, only warnings and error messages are shown on the screen, which usually causes the system's scheduling utility to email the server's administrator so you can fix the problem.

Any deliberate output produced by a task (ie. echo "all done!";) isn't printed to the screen like you'd expect, but rather it is appended to a log file that lives in the inc/app/scheduler/log folder called scheduler.log. The format of a log message is as follows:

2003-09-21 23:00:16 (task_name) Error: all done!

Running Scheduler

Scheduler is a command-line tool, so you don't use a browser to access it. On just about any Unix shell, you can manually call Scheduler with the following command (note: this command is executed from the base directory of your Sitellite installation):

bash$ php -f index scheduler-app

Here is an example of running this command hourly in cron. On the command-line, type:

bash$ crontab -e

Then enter the following info into the cron editor (this is usually the VI editor).

# MIN HOUR DAY MONTH DAYOFWEEK    COMMAND
# once an hour
0 * * * * cd /path/to/sitellite; php -f index scheduler-app

For more informatino about scheduling tasks on your system, please consult your server operating system documentation. For cron, you can access this from the command-line by typing:

bash$ man cron

Command Line Parameters

In addition to the default way of calling the scheduler, you can include additional parameters on the command line to control which tasks are run. The two methods of specifying tasks are as follows:

Specify a single task to run, and only that task will be run.
Specify one or more tasks to skip, and all tasks except those will be run.

The following are examples of these two methods:

# run the scanner task only
php -f index scheduler-app scanner

# run all tasks except the scanner and documents tasks
php -f index scheduler-app -scanner -documents

Troubleshooting

If the scheduler won't run or produces an error, please refer to the troubleshooting option number 4 under SiteSearchTroubleshooting for instructions on ensuring PHP is set up correctly to run the scheduler.

Revised on May 18, 2006 11:25 AM by lux

Back in time (1 more) | Linked from: Apps, Site Search, Access Control, Administration

Topics

Members

Scheduler App