The ZendJobQueue Class

The ZendJobQueue is a PHP class that implements a connection to the Job Queue Daemon

Available since: 5.0

Class Prototype

class ZendJobQueue {

/* Constants */

const int TYPE_HTTP;

const int TYPE_HTTP_RELATIVE;

const int TYPE_SHELL;

const int PRIORITY_LOW;

const int PRIORITY_NORMAL;

const int PRIORITY_HIGH;

const int PRIORITY_URGENT;

const int STATUS_PENDING;

const int STATUS_WAITING_PREDECESSOR;

const int STATUS_RUNNING;

const int STATUS_COMPLETED;

const int STATUS_FAILED;

const int STATUS_OK;

const int STATUS_LOGICALLY_FAILED;

const int STATUS_TIMEOUT;

const int STATUS_REMOVED;

const int STATUS_SCHEDULED;

const int STATUS_SUSPENDED;

const int SORT_NONE;

const int SORT_BY_ID;

const int SORT_BY_TYPE;

const int SORT_BY_SCRIPT;

const int SORT_BY_APPLICATION;

const int SORT_BY_NAME;

const int SORT_BY_PRIORITY;

const int SORT_BY_STATUS;

const int SORT_BY_PREDECESSOR;

const int SORT_BY_PERSISTENCE;

const int SORT_BY_CREATION_TIME;

const int SORT_BY_SCHEDULE_TIME;

const int SORT_BY_START_TIME;

const int SORT_BY_END_TIME;

const int SORT_ASC;

const int SORT_DESC;

const int OK;

const int FAILED;

/* Methods */

void __construct ([ string $queue ])

int createHttpJob (string $url, array $vars, mixed $options)

array getJobStatus (int $job_id)

boolean removeJob (int $job_id)

boolean restartJob (int $job_id)

boolean isSuspended (void)

static boolean isJobQueueDaemonRunning (void)

void suspendQueue (void)

void resumeQueue (void)

array getStatistics (void)

array getConfig (void)

boolean reloadConfig (void)

array getJobInfo (int $job_id)

array getDependentJobs (int $job_id)

array getJobsList (array $query, int $total)

array getApplications (void)

array getSchedulingRules (void)

array getSchedulingRule (int $rule_id)

boolean deleteSchedulingRule (int $rule_id)

boolean suspendSchedulingRule (int $rule_id)

boolean resumeSchedulingRule (int $rule_id)

boolean updateSchedulingRule (int $rule_id, string $script, array $vars, array $options)

static array getCurrentJobParams (void)

static void setCurrentJobStatus (int $completion, string $msg)

}

Class Constants

ZendJobQueue::TYPE_HTTP
A HTTP type of job with an absolute URL
ZendJobQueue::TYPE_HTTP_RELATIVE
A HTTP type of job with a relative URL
ZendJobQueue::TYPE_SHELL
A SHELL type of job
ZendJobQueue::PRIORITY_LOW
A low priority job
ZendJobQueue::PRIORITY_NORMAL
A normal priority job
ZendJobQueue::PRIORITY_HIGH
A high priority job
ZendJobQueue::PRIORITY_URGENT
An urgent priority job
ZendJobQueue::STATUS_PENDING
The job is waiting to be processed
ZendJobQueue::STATUS_WAITING_PREDECESSOR
The job is waiting for its predecessor's completion
ZendJobQueue::STATUS_RUNNING
The job is executing
ZendJobQueue::STATUS_COMPLETED
Job execution has been completed successfully
ZendJobQueue::STATUS_FAILED
The job execution failed
ZendJobQueue::STATUS_OK
The job was executed and reported its successful completion status
ZendJobQueue::STATUS_LOGICALLY_FAILED
The job was executed but reported failed completion status
ZendJobQueue::STATUS_TIMEOUT
Job execution timeout
ZendJobQueue::STATUS_REMOVED
A logically removed job
ZendJobQueue::STATUS_SCHEDULED
The job is scheduled to be executed at some specific time
ZendJobQueue::STATUS_SUSPENDED
The job execution is susspended
ZendJobQueue::SORT_NONE
Disable sorting of result set of getJobsList()
ZendJobQueue::SORT_BY_ID
Sort result set of getJobsList() by job id
ZendJobQueue::SORT_BY_TYPE
Sort result set of getJobsList() by job type
ZendJobQueue::SORT_BY_SCRIPT
Sort result set of getJobsList() by job script name
ZendJobQueue::SORT_BY_APPLICATION
Sort result set of getJobsList() by application name
ZendJobQueue::SORT_BY_NAME
Sort result set of getJobsList() by job name
ZendJobQueue::SORT_BY_PRIORITY
Sort result set of getJobsList() by job priority
ZendJobQueue::SORT_BY_STATUS
Sort result set of getJobsList() by job status
ZendJobQueue::SORT_BY_PREDECESSOR
Sort result set of getJobsList() by job predecessor
ZendJobQueue::SORT_BY_PERSISTENCE
Sort result set of getJobsList() by job persistence flag
ZendJobQueue::SORT_BY_CREATION_TIME
Sort result set of getJobsList() by job creation time
ZendJobQueue::SORT_BY_SCHEDULE_TIME
Sort result set of getJobsList() by job schedule time
ZendJobQueue::SORT_BY_START_TIME
Sort result set of getJobsList() by job start time
ZendJobQueue::SORT_BY_END_TIME
Sort result set of getJobsList() by job end time
ZendJobQueue::SORT_ASC
Sort result set of getJobsList() in direct order
ZendJobQueue::SORT_DESC
Sort result set of getJobsList() in reverse order
ZendJobQueue::OK
Constant to report completion status from the jobs using setCurrentJobStatus()
ZendJobQueue::FAILED
Constant to report completion status from the jobs using setCurrentJobStatus()

Class Methods

ZendJobQueue::__construct

Creates a ZendJobQueue object connected to a Job Queue daemon.

Available since version 5.0

Description

void ZendJobQueue::__construct ([ string $queue ])

Parameters
queue
This can be one of: 1. No value specified - the default binding will be used. 2. A named queue as defined in the named queues directive - In such a case, the client will connect to the binding specified by the directive, and the application name used will be the value provided. 3. A literal binding URL - the URL will be used to connect to the daemon directly, and no application name will be defined. 4. If a string is provided which does not match a binding URL format, and has no alias defined for it, an exception will be thrown. . The default value is taken from default_binding directive

ZendJobQueue::createHttpJob

Creates a new URL based job to make the Job Queue Daemon call given $script with given $vars

Available since version 5.0

Description

int ZendJobQueue::createHttpJob (string $url, array $vars, mixed $options)

Parameters
url
An absolute URL of the script to call
vars
An associative array of variables which will be passed to the script. The total data size of this array should not be greater than the size defined in the zend_jobqueue.max_message_size directive.
options
An associative array of additional options. The elements of this array can define job priority, predecessor, persistence, optional name, additional attributes of HTTP request as HTTP headers, etc The following options are supported: "name" - Optional job name "priority" - Job priority (see corresponding constants) "predecessor" - Integer predecessor job id "persistent" - Boolean (keep in history forever) "schedule_time" - Time when job should be executed "schedule" - CRON-like scheduling command "http_headers" - Array of additional HTTP headers
Return Value

A job identifier which can be used to retrieve the job status

ZendJobQueue::getJobStatus

Retrieves status of previously created job identified by $job_id

Available since version 5.0

Description

array ZendJobQueue::getJobStatus (int $job_id)

Parameters
job_id
a job identifier
Return Value

The array contains status, completion status and output of the job

ZendJobQueue::removeJob

Removes the job from the queue. Makes all dependent jobs fail. In case the job is in progress it will be finished but dependent jobs won't be started anyway. For non-existing jobs the function just returns false. Finished jobs are simply removed from the database

Available since version 5.0

Description

boolean ZendJobQueue::removeJob (int $job_id)

Parameters
job_id
A job identifier
Return Value

The job was removed or not removed

ZendJobQueue::restartJob

Restart a previously executed Job and all its followers.

Available since version 5.0

Description

boolean ZendJobQueue::restartJob (int $job_id)

Parameters
job_id
A job identifier
Return Value

If the job was restarted or not restarted

ZendJobQueue::isSuspended

Checks if Queue is suspended and returns true or false

Available since version 5.0

Description

boolean ZendJobQueue::isSuspended (void)

Return Value

A Job Queue status

ZendJobQueue::isJobQueueDaemonRunning

Checks if the Job Queue Daemon is running

Available since version 5.0

Description

static boolean ZendJobQueue::isJobQueueDaemonRunning (void)

Return Value

Return true if the Job Queue Deamon is running, otherwise it returns false

ZendJobQueue::suspendQueue

Suspends the Job Queue so it will accept new jobs, but won't start them. The jobs which were executed during call to this function will be completed

Available since version 5.0

Description

void ZendJobQueue::suspendQueue (void)

ZendJobQueue::resumeQueue

Resumes the Job Queue so it will schedule and start queued jobs.

Available since version 5.0

Description

void ZendJobQueue::resumeQueue (void)

ZendJobQueue::getStatistics

Returns internal daemon statistics such as up-time, number of complete jobs, number of failed jobs, number of waiting jobs, number of currently running jobs, etc

Available since version 5.0

Description

array ZendJobQueue::getStatistics (void)

Return Value

Associative array

ZendJobQueue::getConfig

Returns the current value of the configuration option of the Job Queue Daemon

Available since version 5.0

Description

array ZendJobQueue::getConfig (void)

Return Value

Associative array of configuration variables

ZendJobQueue::reloadConfig

Re-reads the configuration file of the Job Queue Daemon and reloads all directives that are reloadable

Available since version 5.0

Description

boolean ZendJobQueue::reloadConfig (void)

Return Value

If configuration file was loaded successfully or not

ZendJobQueue::getJobInfo

Returns an associative array with properties of the job with the given id from the daemon database

Available since version 5.0

Description

array ZendJobQueue::getJobInfo (int $job_id)

Parameters
job_id
a job identifier
Return Value

array of job details. The following properties are provided (some of them don't have to always be set): "id" - The job identifier "type" - The job type (see TYPE_* constants) "status" - The job status (see STATUS_* constants) "priority" - The job priority (see PRIORITY_* constants) "persistent" - The persistence flag "script" - The URL or SHELL script name "predecessor" - The job predecessor "name" - The job name "vars" - The input variables or arguments "http_headers" - The additional HTTP headers for HTTP jobs "output" - The output of the job "error" - The error output of the job "creation_time" - The time when the job was created "start_time" - The time when the job was started "end_time" - The time when the job was finished "schedule" - The CRON-like schedule command "schedule_time" - The time when the job execution was scheduled "app_id" - The application name

ZendJobQueue::getDependentJobs

Returns a list of associative arrays with the properties of the jobs which depend on the job with the given identifier

Available since version 5.0

Description

array ZendJobQueue::getDependentJobs (int $job_id)

Parameters
job_id
A job identifier
Return Value

A list of jobs

ZendJobQueue::getJobsList

Returns a list of associative arrays with properties of jobs which conform to a given query

Available since version 5.0

Description

array ZendJobQueue::getJobsList (array $query, int $total)

Parameters
query
An associative array with query arguments The array may contain the following keys which restrict the resulting list: "app_id" - Query only jobs which belong to the given application "name" - Query only jobs with the given name "script" - Query only jobs with a script name similar to the given one (SQL LIKE) "type" - Query only jobs of the given types (bitset) "priority" - Query only jobs with the given priorities (bitset) "status" - Query only jobs with the given statuses (bitset) "rule_id" - Query only jobs produced by the given scheduling rule "scheduled_before" - Query only jobs scheduled before the given date "scheduled_after" - Query only jobs scheduled after the given date "executed_before" - Query only jobs executed before the given date "executed_after" - Query only jobs executed after the given date "sort_by" - Sort by the given field (see SORT_BY_* constants) "sort_direction" - Sort the order (SORT_ASC or SORT_DESC) "start" - Skip the given number of jobs "count" - Retrieve only the given number of jobs (100 by default)
total
The output parameter which is set to the total number of jobs conforming to the given query, ignoring "start" and "count" fields
Return Value

A list of jobs with their details

ZendJobQueue::getApplications

Returns an array of application names known by the daemon

Available since version 5.0

Description

array ZendJobQueue::getApplications (void)

Return Value

A list of applications

ZendJobQueue::getSchedulingRules

Returns an array of all the registered scheduled rules. Each rule is represented by a nested associative array with the following properties: "id" - The scheduling rule identifier "status" - The rule status (see STATUS_* constants) "type" - The rule type (see TYPE_* constants) "priority" - The priority of the jobs created by this rule "persistent" - The persistence flag of the jobs created by this rule "script" - The URL or script to run "name" - The name of the jobs created by this rule "vars" - The input variables or arguments "http_headers" - The additional HTTP headers "schedule" - The CRON-like schedule command "app_id" - The application name associated with this rule and created jobs "last_run" - The last time the rule was run "next_run" - The next time the rule will run

Available since version 5.0

Description

array ZendJobQueue::getSchedulingRules (void)

Return Value

A list of scheduling rules

ZendJobQueue::getSchedulingRule

Returns an associative array with the properties of the scheduling rule identified by the given argument. The list of the properties is the same as in getSchedulingRule()

Available since version 5.0

Description

array ZendJobQueue::getSchedulingRule (int $rule_id)

Parameters
rule_id
The rule identifier
Return Value

Information about the scheduling rule

ZendJobQueue::deleteSchedulingRule

Deletes the scheduling rule identified by the given $rule_id and scheduled jobs created by this rule

Available since version 5.0

Description

boolean ZendJobQueue::deleteSchedulingRule (int $rule_id)

Parameters
rule_id
The rule identifier
Return Value

If scheduling rule was deleted or not deleted

ZendJobQueue::suspendSchedulingRule

Suspends the scheduling rule identified by given $rule_id and deletes scheduled jobs created by this rule

Available since version 5.0

Description

boolean ZendJobQueue::suspendSchedulingRule (int $rule_id)

Parameters
rule_id
The rule identifier
Return Value

If scheduling rule was suspended or not suspended

ZendJobQueue::resumeSchedulingRule

Resumes the scheduling rule identified by given $rule_id and creates a corresponding scheduled job

Available since version 5.0

Description

boolean ZendJobQueue::resumeSchedulingRule (int $rule_id)

Parameters
rule_id
The rule identifier
Return Value

If the scheduling rule was resumed or not resumed

ZendJobQueue::updateSchedulingRule

Updates and reschedules the existing scheduling rule

Available since version 5.0

Description

boolean ZendJobQueue::updateSchedulingRule (int $rule_id, string $script, array $vars, array $options)

Parameters
rule_id
The rule identifier
script
The URL to request
vars
The input variables
options
The same as in createHttpJob()
Return Value

If scheduling rule was updated or not updated

ZendJobQueue::getCurrentJobParams

Decodes an array of input variables passed to the HTTP job

Available since version 5.0

Description

static array ZendJobQueue::getCurrentJobParams (void)

Return Value

The job variables

ZendJobQueue::setCurrentJobStatus

Reports job completion status (OK or FAILED) back to the daemon

Available since version 5.0

Description

static void ZendJobQueue::setCurrentJobStatus (int $completion, string $msg)

Parameters
completion
The job completion status (OK or FAILED)
msg
The optional explanation message