Zend Job Queue - PHP API

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

Table of Contents

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.

createCliJob

Creates a new cli based job to make the Job Queue Daemon execute a command.

createPhpCliJob

Creates a new PHP cli based job to make the Job Queue Daemon call given $script 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

JOB_STATUS_FAILED_BACKEND

int

9.2

The backend server did not respond to the web job

JOB_STATUS_FAILED_TARGET

int

9.2

The job failed to start because of a bad url or script

JOB_STATUS_FAILED_RUNTIME

int

9.2

The job started but failed to complete execution

JOB_STATUS_FAILED_START

int

9.2

The job could not be started

JOB_STATUS_FAILED_PREDECESSOR

int

9.2

The job failed because its predecessor job had failed

JOB_STATUS_FAILED_ABORTED

int

9.2

The job was aborted during execution

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")
                                                                        );
?>

createCliJob

Creates a new cli based job to make the Job Queue Daemon execute a command.

Available Since Version: 9.2

Parameter

Type

Required

Description

command

string

Yes

An command to execute

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
  • "job_timeout" - The timeout for the job
  • "queue_name" - The queue assigned to the job
  • "env" - Array environment strings to add for the script execution
  • "node_name" - String node name where the script should run

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

Code Sample:

<?php
        $queue = new ZendJobQueue();
        $jobId = $queue->createCliJob("php /home/john/email_job.php john@johndomain.com Welcome",                                                                  
                                                                        array("name" => "Welcome Email")
                                                                        );
?>

createPhpCliJob

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

Available Since Version: 9.2

Parameter

Type

Required

Description

script

string

Yes

An absolute script path

vars

array

Yes

An 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
  • "job_timeout" - The timeout for the job
  • "queue_name" - The queue assigned to the job
  • "env" - Array environment strings to add for the script execution
  • "node_name" - String node name where the script should run

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

Code Sample:

<?php
        $queue = new ZendJobQueue();
        $jobId = $queue->createPhpCliJob("/home/john/email_job.php", 
                                                                        array("john@johndomain.com", "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
    • "queue_name" - Query only jobs that are associated with the given queue 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)
    • "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.