Creating a Job

The Zend Server Job Queue component provides the ability to off-load script execution using Jobs Jobs contain information about a specific Job (script to run) that you have set to run in your environment.. A Job is in essence a command to execute a PHP script according to the specific parameters you give it. The Job Queue A simple and manageable system for off-loading tasks from the synchronous user request, to an external, parallel PHP process. component manages the timing and execution of jobs in the system.

Jobs can be created to facilitate a wide range of situations that require you to asynchronously run PHP code. Here are a few examples:

Action Based Jobs for back-end activities which are not a part of the HTTP request-response interaction with end users and need to be executed asynchronously.
Scheduled Jobs that are set to execute according to a predefined schedule.
One-time jobs that need to be run for any reason.
Improving Website performance by offloading processes to a different server.
Optimizing long script execution by deferring running scripts to low peak times.
Unifying script usage by referring to a job script outside the application code instead of repeating the same code for the same functionality. This also provides the added advantage of being able to implement changes throughout the application be editing a single script (instead of editing each individual instance of the script throughout the application's code).

Working with the Job Queue API

The Job Queue API is a set of functions that allow you to create, define and manage the execution of PHP code using a job.

There are three types of Jobs you can create with the Job Queue API:

Queued Jobs - Triggered as a direct result of an end-user activity
Recurring Jobs - Usually defined by the system's programmer. They are usually related to the system's maintenance and are not triggered by an action made by an end-user. The most common existing system to handle such jobs is cron which is usually a part of the operating system on most UNIX-like systems.
One-Time Deferred Tasks (Jobs) - Usually a result of an end-user interaction, and may be deferred in order to optimize the system's load (e.g. cleanup or report generation tasks may be pushed to off-hours) but may also be a part of the application's business logic.

Queued Jobs

This procedure describes how to create a Job that will be triggered as a result of end-user activity using the Job Queue API.

To create a Job that will be triggered as a result of end-user activity:

Open your existing code.
Isolate the part of the code that should be executed as a job.
This code should be a viable script that performs some sort of action that can be run at a later time without disturbing the general functionality (such as sending an e-mail, confirming a credit card etc.).
Put the code into a file and name the file. The location and the name of the file will become the value of the URL parameter therefore always provide descriptive names and place job files in the same location.
In the original code, replace the code you removed with a call to the Job Queue function createHttpJob.
In the function, pass additional GET parameters in the job's URL query string, to handle different data.
Publish the fixed code to your web server.

The next time the code is used the job will be triggered inside the code. To find out how the job ran, and what additional jobs are currently running, go to Overview | Job Queue.

For additional information on handling jobs see Managing Jobs.

Usage Example

Example:

The following example shows what the original code looks like. How it will look like using the Job Queue API, and what the new Job file looks like.

Before converting to a job:

<?php
	function validate_credit_card_number ($string){
	if (preg_match ('/^([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{2,4})$/', $string))
	{
		return TRUE;
	}
	else
	{
		return FALSE;
	}
}// here we call the function to validate the credit card validate_credit_card_number($_POST['credit_code'])

Instead of calling the function from inside the script we will create a job that will be executed when we specify it to run. The script will be replaced with a call to the Job Queue API as follows:

The application script after modification:

<?php
	$cc = $_POST [ 'credit_card'];
	$q = new ZendJobQueue ();
	$ts = date 'Y-m-d H:i:s',time()+10);
	$id = $q -> createHttpJob ('/jobs/validate_credit_card.php', array ('credit_card' =>$cc), 
			array ('name' =>'Credit card validation using a single job execution scheduled to run after 10 seconds', 'schedule_time' =>$ts));
			if (!$id){exit(1)};

The new job script:

<?php
	function validate_credit_card_number($string)
		{
		 if(preg_match('/^([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{2,4})$/', $string))
		    {
		        return ZendJobQueue::setCurrentJobStatus(ZendJobQueue::OK);
		    }
		    else
		    {
		        return ZendJobQueue::setCurrentJobStatus(ZendJobQueue::FAILED);
		    }
		}

	$params = ZendJobQueue::getCurrentJobParams();

	validate_credit_card_number($params['credit_card']);
?>

Recurring Jobs

This procedure describes how to create a recurring Job. A recurring job will be executed periodically based on a defined schedule.

Creating recurring jobs from API is usually useful when the application’s workflow requires the creation (and usually subsequent deletion) of recurring tasks following some user interaction. For example, in a feed aggregator, it might make sense to create a recurring job that hourly pulls updates for each new feed added by the user. Another example might be a reporting system in which users can create and delete daily, weekly or monthly reports.

To create a recurring job:

Follow the instructions in Queued Jobs to create an createHttpJob job using the API.
Pass the schedule option as part of the options parameter to describe the recurrance schedule.

The schedule option is a CRON-like expression that consists of string with 5 fields separated by spaces. The fields define the minute, hour, day of month, month and day of week (in this order) in which the job will run.

In each field, you can use one of the following notations:

A single number (with valid ranges listed below)
An asterisk (‘*’) to designate “any” (e.g. to run a on every day of the month, put ‘*’ in the 4th field)
A comma-separated list of values (e.g. to run a job on Sundays, Tuesdays and Thursdays, put ‘0,2,4’in the 5th field)
An interval specified by ‘*/n’ where n is the interval (e.g. to run a job every 2 hours, use ‘*/2’ in the2nd field). To be accurate, this means “on every hour that evenly divides by two – meaning 2,4,6,…)

Usage Example

Example:

The following example represents a job that will run every day at 3:15am:

$job = $jq->createHttpJob('http://localhost/jobs/feed/405', 
		 null, array(
'schedule' => '15 3 * * *'

Ranges for each field:

Field	Range	Comments
Minute	0 - 59
Hour	0 - 23	In 24 hour format, where 0 is midnight
Day of Month	1 - 31	29,30 and 31 will only work for months of that length
Month	1 - 12
Day of Week	0 - 7	Sunday is either 0 or 7

One-Time Deferred Tasks (Jobs)

This procedure describes how to create a one-time deferred task. In some use cases, it makes sense to defer a certain task to a later time. For example, many applications have clear peak hours (e.g. between 8am and 11pm, or like in many Intranet applications, during office work hours).

If these applications need to perform some off-line processing, it might make sense to defer some of the heavy processing tasks to off hours (in our examples to late night or early morning hours), in order to maximize the efficiency of hardware utilization.

To create a time deferred task:

Follow the instructions in Queued Jobs to create an createHttpJob job using the API.
Pass a date/time string as the schedule_time option, as part of the options array passed as the 3rd parameter to createHttpJob().

Note:

The format used in date() to pass the execution time – this is an SQL-like ‘YYYY-MM-DD hh:mm:ss’format (e.g. “2009-06-25 23:45:00” for June 25th 2009 at 45 minutes past 11pm).

Zend Job Queue is not designed to execute jobs exactly on the specified time. For example, if the queue is limited to execute 10 jobs concurrently (more on that later on), and 1,000 jobs are scheduled for the exact same time – jobs will have to wait until other jobs finish. You should consider the schedule_time option as a request not to run a job before this time.

Usage Example

Example:

The following example shows a time-deferred task that has been scheduled to run a process at 2:00am.

$options = array(
'schedule_time' => date('Y-m-d h:i:s', strtotime('tomorrow 
		 2am'))
);
$jq->createHttpJob('http://localhost/jobs/formproc.php', 
		 $_POST, $options);

Note:

The format used in date() to pass the execution time – this is an SQL-like ‘YYYY-MM-DD hh:mm:ss’format (e.g. “2009-06-25 23:45:00” for June 25th 2009 at 45 minutes past 11pm).