Zend Job Queue - PHP API

This topic lists the PHP API functions of the Zend Job Queue.

Table of Contents

• The ZendJobQueue Class

• The ZendJobQueueException Class

The ZendJobQueue Class

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

Available Since Version: 5.0

ZendJobQueue Functions

Function	Description
__construct	Creates a ZendJobQueue object connected to a Job Queue daemon.
createHttpJob	Creates a new URL based job to make the Job Queue Daemon call given $url with given $vars.
getJobStatus	Retrieves status of previously created job identified by its ID.
removeJob	Removes the job from the queue. Makes all dependent jobs fail. If the job is in progress, it will be finished, but dependent jobs will not be started. For non-existing jobs, the function returns false. Finished jobs are removed from the database.
restartJob	Restart a previously executed Job and all its followers.
isSuspended	Checks if the Job Queue is suspended and returns true or false.
isJobQueueDaemonRunning	Checks if the Job Queue Daemon is running.
suspendQueue	Suspends the Job Queue so it will accept new jobs, but will not start them. The jobs which were executed during the call to this function will be completed.
resumeQueue	Resumes the Job Queue so it will schedule and start queued jobs.
getStatistics	Returns internal daemon statistics such as up-time, number of complete jobs, number of failed jobs, number of logically failed jobs, number of waiting jobs, number of currently running jobs, etc.
getStatisticsByTimespan	See getStatistics API. Only checks jobs whose status were changed in a given timespan (seconds).
getConfig	Returns the current value of the configuration option of the Job Queue Daemon.
getQueues	Returns the list of available queues.
reloadConfig	Re-reads the configuration file of the Job Queue Daemon, and reloads all directives that are reloadable.
getJobInfo	Returns an associative array with properties of the job with the given ID from the daemon database.
getDependentJobs	Returns a list of associative arrays with the properties of the jobs which depend on the job with the given identifier.
getJobsList	Returns a list of associative arrays with properties of jobs which conform to a given query.
getApplications	Returns an array of application names known by the daemon.
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
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 getSchedulingRules().
deleteSchedulingRule	Deletes the scheduling rule identified by the given $rule_id and scheduled jobs created by this rule.
suspendSchedulingRule	Suspends the scheduling rule identified by given $rule_id and deletes scheduled jobs created by this rule.
resumeSchedulingRule	Resumes the scheduling rule identified by given $rule_id and creates a corresponding scheduled job.
updateSchedulingRule	Updates and reschedules the existing scheduling rule.
getCurrentJobParams	Decodes an array of input variables passed to the HTTP job.
setCurrentJobStatus	Reports job completion status (OK or FAILED) back to the daemon.
getCurrentJobId	Returns the current job ID. Returns NULL if not called within a job context.

ZendJobQueue Constants

Constant	Type	Available Since Version	Description
TYPE_HTTP	int	5.0	A HTTP type of job with an absolute URL
TYPE_HTTP_RELATIVE	int	5.0	A HTTP type of job with a relative URL
PRIORITY_LOW	int	5.0	A low priority job
PRIORITY_NORMAL	int	5.0	A normal priority job
PRIORITY_HIGH	int	5.0	A high priority job
PRIORITY_URGENT	int	5.0	An urgent priority job
JOB_STATUS_PENDING	int	5.0	The job is waiting to be processed
JOB_STATUS_WAITING_PREDECESSOR	int	5.0	The job is waiting for its predecessor's completion
JOB_STATUS_RUNNING	int	5.0	The job is executing
JOB_STATUS_COMPLETED	int	5.0	Job execution has been completed successfully
JOB_STATUS_FAILED	int	5.0	The job execution failed
JOB_STATUS_OK	int	5.0	The job was executed and reported its successful completion status
JOB_STATUS_LOGICALLY_FAILED	int	5.0	The job was executed but reported failed completion status
JOB_STATUS_TIMEOUT	int	5.0	Job execution timeout
JOB_STATUS_REMOVED	int	5.0	A logically removed job
JOB_STATUS_SCHEDULED	int	5.0	The job is scheduled to be executed at some specific time
JOB_STATUS_SUSPENDED	int	5.0	The job execution is susspended
SORT_JOB_NONE	int	5.0	Disable sorting of result set of getJobsList()
SORT_BY_ID	int	5.0	Sort result set of getJobsList() by job id
SORT_BY_TYPE	int	5.0	Sort result set of getJobsList() by job type
SORT_BY_SCRIPT	int	5.0	Sort result set of getJobsList() by job script name
SORT_BY_APPLICATION	int	5.0	Sort result set of getJobsList() by application name
SORT_BY_NAME	int	5.0	Sort result set of getJobsList() by job name
SORT_BY_PRIORITY	int	5.0	Sort result set of getJobsList() by job priority
SORT_BY_STATUS	int	5.0	Sort result set of getJobsList() by job status
SORT_BY_PREDECESSOR	int	5.0	Sort result set of getJobsList() by job predecessor
SORT_BY_PERSISTENCE	int	5.0	Sort result set of getJobsList() by job persistence flag
SORT_BY_CREATION_TIME	int	5.0	Sort result set of getJobsList() by job creation time
SORT_BY_SCHEDULE_TIME	int	5.0	Sort result set of getJobsList() by job schedule time
SORT_BY_START_TIME	int	5.0	Sort result set of getJobsList() by job start time
SORT_BY_END_TIME	int	5.0	Sort result set of getJobsList() by job end time
SORT_ASC	int	5.0	Sort result set of getJobsList() in direct order
SORT_DESC	int	5.0	Sort result set of getJobsList() in reverse order
OK	int	5.0	Constant to report completion status from the jobs using setCurrentJobStatus()
FAILED	int	5.0	Constant to report completion status from the jobs using setCurrentJobStatus()

__construct

Creates a ZendJobQueue object connected to a Job Queue daemon.

Available Since Version: 5.0

Parameter	Type	Required	Description
binding	string	No	This can be one of: 1. No value specified - the default binding will be used. 2. A literal binding URL - the URL will be used to connect to the daemon directly

Code Sample:

			<?php
			$queue = new ZendJobQueue();
			?>
		

createHttpJob

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

Available Since Version: 5.0

Parameter	Type	Required	Description
url	string	Yes	An absolute URL of the script to call.
vars	array	Yes	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	mixed	Yes	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 "job_timeout" - The timeout for the job "queue_name" - The queue assigned to the job "validate_ssl" - Boolean (validate ssl certificate")

Return Value: int - A job ID which can be used to retrieve the job status.

Code Sample:

			<?php
			$queue = new ZendJobQueue();
			$jobId = $queue->createHttpJob("http://my.domain/email_job.php", 
			array("email" => "john@johndomain.com", "email_template" => "welcome"),
			array("name" => "Welcome Email")
			);
			?>
		

getJobStatus

Retrieves status of previously created job identified by its ID.

Available Since Version: 5.0

Parameter	Type	Required	Description
job_id	int	Yes	A job ID.

Return Value: array - The array contains status, completion status and output of the job.

removeJob

Removes the job from the queue. Makes all dependent jobs fail. If the job is in progress, it will be finished, but dependent jobs will not be started. For non-existing jobs, the function returns false. Finished jobs are removed from the database.

Available Since Version: 5.0

Parameter	Type	Required	Description
job_id	int	Yes	A job ID.

Return Value: boolean - The job was removed or not removed.

restartJob

Restart a previously executed Job and all its followers.

Available Since Version: 5.0

Parameter	Type	Required	Description
job_id	int	Yes	A job id

Return Value: boolean - If the job was restarted or not restarted.

isSuspended

Checks if the Job Queue is suspended and returns true or false.

Available Since Version: 5.0

Return Value: boolean - A Job Queue status.

isJobQueueDaemonRunning

Checks if the Job Queue Daemon is running.

Available Since Version: 5.0

Return Value: boolean - Return true if the Job Queue Deamon is running, otherwise it returns false.

suspendQueue

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

Available Since Version: 5.0

resumeQueue

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

Available Since Version: 5.0

getStatistics

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

Available Since Version: 5.0

Return Value: array - Associative array.

getStatisticsByTimespan

See getStatistics API. Only checks jobs whose status were changed in a given timespan (seconds).

Available Since Version: 5.0

Parameter	Type	Required	Description
time_span	int	Yes	The time span in seconds.

Return Value: array - Associative array.

getConfig

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

Available Since Version: 5.0

Return Value: array - Associative array of configuration variables.

getQueues

Returns the list of available queues.

Available Since Version: 5.5

Return Value: array - Associative array of queues information.

reloadConfig

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

Available Since Version: 5.0

Return Value: boolean - If configuration file was loaded successfully or not.

getJobInfo

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

Available Since Version: 5.0

Parameter	Type	Required	Description
job_id	int	Yes	A job ID.

Return Value: array -

Array of job details.

The following properties are provided (some do not 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
• "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
• "queue_name" - The queue name

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

Parameter	Type	Required	Description
job_id	int	Yes	A job ID.

Return Value: array - A list of jobs.

getJobsList

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

Available Since Version: 5.0

Parameter	Type	Required	Description
query	array	Yes	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	int	Yes	The output parameter which is set to the total number of jobs conforming to the given query, ignoring "start" and "count" fields.

Return Value: array - A list of jobs with their details.

getApplications

Returns an array of application names known by the daemon.

Available Since Version: 5.0

Return Value: array - A list of applications.

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

Return Value: array - A list of scheduling rules.

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 getSchedulingRules().

Available Since Version: 5.0

Parameter	Type	Required	Description
rule_id	int	Yes	The rule identifier.

Return Value: array - Information about the scheduling rule.

deleteSchedulingRule

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

Available Since Version: 5.0

Parameter	Type	Required	Description
rule_id	int	Yes	The rule identifier.

Return Value: boolean - If scheduling rule was deleted or not deleted.

suspendSchedulingRule

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

Available Since Version: 5.0

Parameter	Type	Required	Description
rule_id	int	Yes	The rule identifier.

Return Value: boolean - If scheduling rule was suspended or not suspended.

resumeSchedulingRule

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

Available Since Version: 5.0

Parameter	Type	Required	Description
rule_id	int	Yes	The rule identifier.

Return Value: boolean - If the scheduling rule was resumed or not resumed.

updateSchedulingRule

Updates and reschedules the existing scheduling rule.

Available Since Version: 5.0

Parameter	Type	Required	Description
rule_id	int	Yes	The rule identifier.
script	string	Yes	The URL to request.
vars	array	Yes	The input variables.
options	array	Yes	The same as in createHttpJob().

Return Value: boolean - If scheduling rule was updated or not updated.

getCurrentJobParams

Decodes an array of input variables passed to the HTTP job.

Available Since Version: 5.0

Return Value: array - The job variables.

setCurrentJobStatus

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

Available Since Version: 5.0

Parameter	Type	Required	Description
completion	int	Yes	The job completion status (OK or FAILED).
msg	string	Yes	The optional explanation message.

getCurrentJobId

Returns the current job ID. Returns NULL if not called within a job context.

Available Since Version: 5.0

Return Value: int - The job ID.

The ZendJobQueueException Class

A ZendJobQueueException instance is thrown in cases where an ZendJobQueue API call fails.

Available Since Version: 5.0

ZendJobQueueException Functions

Function	Description
getCode	Gets the exception code.
getMessage	Gets the exception message.

ZendJobQueueException Constants

Constant	Type	Available Since Version	Description
JQ_ERR_UNKNOWN	int	5.0	an unknown error occured
JQ_ERR_INVALID_PARAMETER	int	5.0	an invalid parameter was provided
JQ_ERR_SERVER_ERR	int	5.0	an internal Job Queue daemon error has occured
JQ_ERR_SERVER_BUSY	int	5.0	the Job Queue daemon was too busy to execute the API call
JQ_ERR_NETWORK_ERR	int	5.0	a network error has occured
JQ_ERR_TIMEOUT	int	5.0	an API timeout has exceeded
JQ_ERR_LICENSE	int	5.0	a licensing problem

getCode

Gets the exception code.

Available Since Version: 5.0

Return Value: int - The exception codes: JQ_ERR_INVALID_PARAMETER JQ_ERR_SERVER_ERR JQ_ERR_SERVER_BUSY JQ_ERR_NETWORK_ERR JQ_ERR_UNKNOWN JQ_ERR_TIMEOUT JQ_ERR_LICENSE

getMessage

Gets the exception message.

Available Since Version: 5.0

Return Value: string - The exception message.