ZendHQ JobQueue - PHP API Reference

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

Table of Contents

• ZendHQ\JobQueue Namespace

  • The Job Class

  • The CLIJob Class

  • The HTTPJob Class

  • The JobDefinition Interface

  • The JobOptions Class

  • The JobQueue Class

  • The Queue Class

  • The QueueDefinition Class

  • The RecurringSchedule Class

  • The Schedule Interface

  • The ScheduleTime Class

• ZendHQ\JobQueue\Exception Namespace

  • The InvalidArgument Class

  • The InvalidMethod Class

  • The NotInitialized Class

  • The NetworkError Class

  • The Timeout Class

  • The ServerError Class

  • The LicenseError Class

  • The Other Class

 

ZendHQ\JobQueue namespace

 

The Job Class

Job Methods

Methods	Description
getQueueName	Returns the name of the queue
getId	Returns the ID value uniquely identifying the job
getJobDefinition	Returns the job definition
getSchedule	Returns the schedule of the job
getJobOptions	Returns job options
getStatus	Returns the status of the job
getRetryCount	Returns the retry count
getOutput	Returns the output of the job if the job has been finished and output persisted
getCreationTime	Returns the time when the job was created
getScheduledTime	Returns the next scheduled execution time
getCompletionTime	Returns the last completion time if the job has been completed
refresh	Refreshes the job by requesting updated information from the daemon

 

Job Constants

Constant	Type	Description
STATUS_CREATED	int	The job is created, but not scheduled yet
STATUS_SCHEDULED	int	The job is scheduled
STATUS_WAITING_ON_PARENT	int	The job is waiting for the parent to be completed
STATUS_RUNNING	int	The job is running
STATUS_SUSPENDED	int	The job is suspended
STATUS_TIMEOUT	int	The job has timed out
STATUS_FAILED_NO_WORKER	int	The job failed because there is no worker
STATUS_FAILED_WORKER_ERROR	int	The job failed because of a worker error
STATUS_REMOVED	int	The job is canceled and deleted
STATUS_COMPLETED	int	The job is completed successfully
STATUS_UNKNOWN	int	The job status is unknown due to an interruption

 

getQueueName

Return value: string - Queue name

getId

Return value: int - The ID value

getJobDefinition

Return value: JobDefinition - The job definition

getSchedule

Return value: Schedule - The schedule

getJobOptions

Return value: JobOptions - Job options

getStatus

Return value: int - Job status value

getRetryCount

Return value: int - Retry count

getOutput

Return value: string|null - Output

getCreationTime

Return value: DateTimeInterface - Creation time

getScheduledTime

Return value: DateTimeInterface - Scheduled execution time

getCompletionTime

Return value: DateTimeInterface|null - Completion time if completed, otherwise null

refresh

Return value: void

@throws NetworkError if it

1. is not connected to the ZendHQ daemon

2. failed to communicate with the ZendHQ daemon

3. message parsing errors

@throws InvalidArgument if

1. there's no such job

 

The CLIJob Class

Implements JobDefinition

CLIJob Methods

Methods	Description
__construct	Constructs CLI job definition
getName	Returns the optional name of the job
setName	Sets or unsets the name of the job
setEnv	Adds environment variables to the CLI job
getEnv	Returns the environment
getCommand	Returns the full command line

 

__construct

Parameter	Type	Required	Description
command	string	yes	The full command line, including arguments and options

Throws InvalidArgument if:

1. the $command is not valid (quotes not closed etc.)

The value of the $command argument is processed using the following rules:

• Backslash `\` characters followed by one of the following characters `\`, ` `, `"`, and `'` are removed and the following character peserves the literal value of the character; backslashes preceeding characters without special meaning are left unmodified.

• Enclosing characters in single `'` quotes preserve the literal value of each character within the quotes; a single `'` quote may not occur between single quotes.

• Enclosing characters in double `"` quotes preserve the literal value of each character within the quotes, with the exception of `\`; a double `"` quote may be quoted within double quotes by preceeding it with a backslash.

getName

Return value: string - Optional name of the job if set, otherwise null

setName

Parameter	Type	Required	Description
name	string	yes	The Job name

Unsets the name if $name is null or and empty string.

Return value: CLIJob - self

setEnv

Parameter	Type	Required	Description
name	string	yes	Name of the environment variable
value	string	yes	Value of the environment variable

Note that the default environment for CLI jobs is empty and `PATH` must be specified manually if needed.

Return value: CLIJob - self

getEnv

Return value: array<string, string> - Array of name/value pairs

getCommand

Return value: string - The full command line

 

The HTTPJob Class

Implements JobDefinition

HTTPJob Methods

Methods	Description
__construct	Constructs HTTP job definition
getName	Returns the optional name of the job
setName	Sets or unsets the name of the job
setURL	Sets the URL of the HTTP request
setMethod	Sets the HTTP request method
setContentType	Sets the HTTP body content type
addHeader	Adds request headers to the HTTP job definition
addQueryStringArgument	Adds query string arguments to the HTTP job definition
addBodyParam	Adds body parameters to the HTTP job definition
setRawBody	Sets the raw body for the HTTP job definition
getURL	Returns the URL of the HTTP request
getMethod	Returns the HTTP request method
getContentType	Returns the HTTP body content type
getHeaders	Returns all the HTTP request headers
getBody	Returns the encoded HTTP request body

HTTPJob Constants

Constant	Type	Description
HTTP_METHOD_GET	string	HTTP `GET` request
HTTP_METHOD_POST	string	HTTP `POST` request
HTTP_METHOD_PUT	string	HTTP `PUT` request
CONTENT_TYPE_JSON	int	HTTP content type `application/json`
CONTENT_TYPE_URL_ENCODED	int	HTTP content type `application/x-www-form-urlencoded`
CONTENT_TYPE_ZEND_SERVER	int	HTTP content type compatible with Zend Server

__construct

Parameter	Type	Required	Description
url	string	yes	The URL of the HTTP request
method	string	yes	The HTTP request method
contentType	int	yes	The HTTP body content type

Throws InvalidArgument if:

1. $url is not a valid URL

2. $method is not one of 'GET', 'POST', or 'PUT'

3. $contentType is not a valid value

See the HTTPJob Constants table for method and contentType values.

getName

Return value: string - Optional name of the job if set, otherwise null

setName

Parameter	Type	Required	Description
name	string	yes	The Job Name

Unsets the name if $name is null or and empty string.

Return value: HTTPJob - self

setURL

Parameter	Type	Required	Description
url	string	yes	The URL of the HTTP request

Throws InvalidArgument if:

1. $url is not a valid URL

Return value: HTTPJob - self

setMethod

Parameter	Type	Required	Description
method	string	yes	The HTTP request method

Throws InvalidArgument if:

1. $method is not one of 'GET', 'POST', or 'PUT'

Return value: HTTPJob - self

setContentType

Parameter	Type	Required	Description
contentType	int	yes	The HTTP body content type

Throws InvalidArgument if:

1. $contentType is not a valid value

Return value: HTTPJob - self

addHeader

Parameter	Type	Required	Description
headerName	string	yes	Name of the header
value	string	yes	Request header value

Return value: HTTPJob - self

addQueryStringArgument

Parameter	Type	Required	Description
key	string	yes	The key
value	string	yes	The value

Return value: HTTPJob - self

addBodyParam

Parameter	Type	Required	Description
key	string	yes	The key
value	string	yes	The value

Throws InvalidMethod if:

1. method is 'GET'

2. addRawBody() is already called

Return value: HTTPJob - self

setRawBody

Parameter	Type	Required	Description
content	string	yes	The raw body content

Throws InvalidMethod if:

1. method is 'GET'

2. addBodyParam() is already called

Return value: HTTPJob - self

getUrl

Return value: string - The URL

getMethod

Return value: string - The HTTP request method

getContentType

Return value: int - The HTTP body content type

getHeaders

Return value: array<string, string> - An array of name/value pairs

getBody

You first queue the job and then check the body.

Throws InvalidMethod if:

a) job is not queued yet and body has been provided

Return value: string|null - The encoded HTTP request body. Returns null if the HTTP request is not a 'POST' or 'PUT'

 

The JobDefinition Interface

JobDefinition Methods

Methods	Description
getName	Returns the optional name of the job
setName	Sets or unsets the name of the job

getName

Return value: string - Optional name of the job if set, otherwise null

setName

Parameter	Type	Required	Description
name	string	no	Name of the job or null

Unsets the name if $name is null or and empty string

Return value: JobDefinition - self

 

The JobOptions Class

JobOptions Methods

Methods	Description
__construct	Constructs job options
getPriority	Returns the priority of the job
getTimeout	Returns the timeout value in seconds
getAllowedRetries	Returns the number of allowed retries
getRetryWaitTime	Returns the wait time in seconds between retries
getPersistOutput	Returns the persist job output option value
willValidateSsl	Returns true if SSL validation is enabled
setPriority	Sets the job priority
setTimeout	Sets the timeout value in seconds
setAllowedRetries	Sets the number of allowed retries
setRetryWaitTime	Sets the wait time in seconds between retries
setPersistOutput	Sets the persist job output option
validateSsl	Enables or disbles SSL validation for HTTP jobs

JobOptions Constants

Constant	Type	Description
PRIORITY_LOW	int	Low priority
PRIORITY_NORMAL	int	Normal priority
PRIORITY_HIGH	int	High priority
PRIORITY_URGENT	int	Urgent priority
PERSIST_OUTPUT_NO	int	Do not persist job output
PERSIST_OUTPUT_YES	int	Always persist job output
PERSIST_OUTPUT_ERROR	int	Persist job output when failed

__construct

Parameter	Type	Required	Description
priority	int|null	yes	Priority of the job
timeout	int|null	yes	Job timeout in seconds
allowedRetries	int|null	yes	Number of allowed retries
retryWaitTime	int|null	yes	Wait time in seconds between retries
persistOutput	int|null	yes	Persist job output option
validateSsl	bool|null	yes	Validate SSL option for HTTP jobs

Throws InvalidArgument if:

1. $priority value is not valid

2. $timeout is <= 0 or $timeout > 2147483

3. $allowedRetries < 0

4. $retryWaitTime < 0 or $retryWaitTime > 2147483

5. $persistOutput value is not valid

Default job options from the queue are used for any job option values that are null.

getPriority

Return value: int|null - Priority of the job

getTimeout

Return value: int|null - Timeout value in seconds

getAllowedRetries

Return value: int|null - Number of allowed retries

getRetryWaitTime

Return value: int|null - Wait time in seconds

getPersistOutput

Return value: int|null - Persist job output value

willValidateSsl

Return value: bool|null - True if SSL validation is enabled

setPriority

Parameter	Type	Required	Description
priority	int	yes	The priority value

Throws InvalidArgument if:

1. the $priority value is invalid

Return value: JobOptions - self

setTimeout

Parameter	Type	Required	Description
seconds	int	yes	Timeout value

Throws InvalidArgument if:

a) $seconds <= 0 or $seconds > 2147483

Return value: JobOptions - self

setAllowedRetries

Parameter	Type	Required	Description
retries	int	yes	Number of retries

Throws InvalidArgument if:

a) $retries < 0

Return value: JobOptions - self

setRetryWaitTime

Parameter	Type	Required	Description
seconds	int	yes	Wait time

Throws InvalidArgument if:

a) $seconds <= 0 or $seconds > 2147483

Return value: JobOptions - self

setPersistOutput

Parameter	Type	Required	Description
persist	int	yes	The persist job output value

Throws InvalidArgument if:

a) the $persist value is invalid

Return value: JobOptions - self

validateSsl

Parameter	Type	Required	Description
validate	bool	yes	Validate SSL option

Return value: JobOptions - self

 

The JobQueue Class

JobQueue Methods

Methods	Description
__construct	Constructs the JobQueue object and connects to the ZendHQ daemon
getQueues	Returns an array with all the Job Queue queues
getDefaultQueue	Returns the default Job Queue queue
getQueue	Returns the queue identified by $queueName
hasQueue	Returns true if a queue with the given name exists
addQueue	Adds a queue with the given name and definition
modifyQueue	Modifies the queue identified by the name
deleteQueue	Deletes the queue and all the jobs in the queue

 

__construct

Parameter	Type	Required	Description
endpoint	string	no	0mq endpoint

Throws InvalidArgument if:

a) the optional 0mq $endpoint is invalid

Throws NetworkError if:

a) failed to connect to the ZendHQ daemon

b) protocol mismatch (daemon and extension versions are different)

c) message parsing errors

Throws LicenseError if:

a) ZendHQ license is missing, invalid, or expired

If the $endpoint parameter is omitted, then connects to the default ZendHQ daemon specified in the INI file.

getQueues

Return value: array<int, string> - Array of queue ID value and name pairs

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

getDefaultQueue

Return value: Queue - The default Job Queue queue

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

Throws ServerError if:

a) ZendHQ daemon did not respond with a valid queue

getQueue

Parameter	Type	Required	Description
queueName	string	yes	The name of the queue

Return value: Queue - The queue

 

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

Throws InvalidArgument if:

a) no queue with the given $queueName

Throws ServerError if:

a) ZendHQ daemon did not respond with a valid queue

hasQueue

Parameter	Type	Required	Description
queueName	string	yes	The name of the queue

Return value: bool - True if a queue with the given name exists, otherwise false

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

Throws ServerError if:

a) ZendHQ daemon did not respond with a valid queue

addQueue

Parameter	Type	Required	Description
queueName	string	yes	The name of the queue
queueDefinition	QueueDefinition	no	Optional queue definition

Return value: Queue - The added queue instance

Throws InvalidArgument if:

a) queue name is empty or longer than 256 characters

b) a queue with the given name already exists

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

If the optional $queueDefinition argument is omitted, then uses default queue definition values configured in the ZendHQ daemon.

modifyQueue

Parameter	Type	Required	Description
queue	string|Queue	yes	The queue (queue name or queue instance)
queueDefinition	QueueDefinition	yes	Queue definition with changed attributes

Return value: Queue - The modified queue instance

Throws InvalidArgument if:

a) the queue does not exist

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

deleteQueue

Parameter	Type	Required	Description
queue	string|Queue	yes	The queue to be deleted (queue name or instance)

Throws InvalidArgument if:

a) the queue does not exist

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

Throws ServerError if:

a) the queue is not suspended

The queue MUST be suspended before it can be deleted.

 

The Queue Class

Queue Methods

Methods	Description
getName	Returns the name uniquely identifying the queue
getId	Returns the numeric ID value uniquely identifying the queue
getDefinition	Returns the queue definition
getStatus	Returns the current status of the queue
refresh	Refreshes the queue by requesting updated information from the daemon
suspend	Suspends the queue and optionally waits until the queue is suspended
resume	Resumes the queue and optionally waits until the queue is resumed
getJobs	Returns an array with all the scheduled and running jobs in this queue
getJobsByName	Returns an array with all the scheduled and running jobs in this queue that have the specified name
getJob	Returns a job identified by the $id value in this queue
scheduleJob	Schedules a job for execution in this queue
cancelJob	Cancels the job

Queue Constants

Constant	Type	Description
STATUS_RUNNING	int	Queue is running
STATUS_SUSPENDED	int	Queue is suspended
STATUS_DELETED	int	Queue is deleted

getName

Return value: string - The name of the queue

getId

Return value: int - The ID value

getDefinition

Return value: QueueDefinition - The queue definition

getStatus

Return value: int - The queue status value

refresh

Return value: void

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

suspend

Parameter	Type	Required	Description
timeout	int	no	Time in seconds to wait

Return value: void

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

Throws Timeout if:

a) the queue did not suspend within the specified time

If the $timeout argument is zero, then returns immediately after sending

the request to the ZendHQ daemon without waiting.

resume

Parameter	Type	Required	Description
timeout	int	no	Time in seconds to wait

Return value: void

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

Throws Timeout if:

a) the queue did not resume within the specified time

If the $timeout argument is zero, then returns immediately after sending

the request to the ZendHQ daemon without waiting.

getJobs

Return value: array<int, Job> - Array of job instances

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

The returned array contains job instances in the "native" execution order

getJobsByName

Parameter	Type	Required	Description
name	string	yes	Job name

Return value: array<int, Job> - Array of job instances

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

The returned array contains job instances in the "native" execution order

getJob

Parameter	Type	Required	Description
id	int	yes	The ID value of the job

Return value: Job - The job instance

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

Throws InvalidArgument if:

a) no job with the given $id

Throws ServerError if:

a)ZendHQ daemon didn't respond with a valid job

scheduleJob

Parameter	Type	Required	Description
job	JobDefinition	yes	The definition of the job
schedule	Schedule	no	Execution schedule of the job
jobOptions	JobOptions	no	Options for this job

Return value: Job - The scheduled job

Throws NotInitialized if:

a) the Queue object is not associated with any JobQueue objects

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

Throws ServerError if:

a) ZendHQ daemon didn't respond with a valid job

Schedules a job for execution in this queue and returns the Job instance updated by the ZendHQ daemon.

If the $schedule argument is null, then schedules the job for an immediate execution.

If the $jobOptions argument is null, then uses default job options from the queue.

cancelJob

Parameter	Type	Required	Description
job	int|Job	yes	The job to be cancelled (ID value or Job instance)

Return value: void

Throws NetworkError if:

a) not connected to ZendHQ daemon

b) failed to communicate with the ZendHQ daemon

c) message parsing errors

Throws InvalidArgument if:

a) the $job object is not valid

b) no such job

Cancels the previously scheduled job and marks it as deleted (Job::STATUS_REMOVED)

If the job was running and the test result of the job is not known, then marks it as unknown (Job::STATUS_UNKNOWN)

 

The QueueDefinition Class

QueueDefinition Methods

Methods	Description
__construct	Constructs the queue definition instance
getPriority	Returns the priority of the queue
getDefaultJobOptions	Returns default job options for jobs scheduled in this queue
setPriority	Sets the priority of the queue
setDefaultJobOptions	Sets default job opitons for jobs scheduled in this queue

__construct

Parameter	Type	Required	Description
priority	int	yes	Queue priority value
defaultJobOptions	JobOptions	yes	Default options for jobs scheduled in this queue

Throws InvalidArgument if:

a) the $priority value is invalid

Job Queue default values are used for any values that are null including null values in the $defaultJobOptions instance.

getPriority

Return value: int|null - Queue priority value

getDefaultJobOption

Return value: JobOptions|null - Default job options

setPriority

Parameter	Type	Required	Description
priority	int	yes	The queue priority value

Throws InvalidArgument if:

a) the $priority value is invalid

Return value: QueueDefinition - self

setDefaultJobOptions

Parameter	Type	Required	Description
defaultJobOptions	JobOptions	yes	Default job options

Return value: QueueDefinition - self

 

The RecurringSchedule Class

The RecurringSchedule class implements the Schedule interface

RecurringSchedule Methods

Methods	Description
__construct	Constructs the recurring schedule instance
getSchedule	Returns the schedule

__construct

Parameter	Type	Required	Description
crontab	string	yes	Cron expression with the recurring schedule

Throws InvalidArgument if:

a) the $crontab string is invalid

getSchedule

Return value: string - Schedule

 

The Schedule Interface

Schedule Methods

Methods	Description
getSchedule	Returns the schedule

getSchedule

Return value: mixed -

The ScheduledTime Class

The RecurringSchedule class implements the Schedule interface

ScheduledTime Methods

Method	Description
__construct	Constructs the scheduled time instance
getSchedule	Returns the schedule

__construct

Parameter	Type	Required	Description
dateTime	DateTimeInterface	yes	Date and time

Throws InvalidArgument if:

a) the $dateTime object is not initialized

getSchedule

Return value: DateTimeImmutable -

 

ZendHQ\JobQueue\Exception Namespace

 

The InvalidArgument Class

The InvalidArgument class extends the InvalidArgumentException class

Invalid argument value error

 

The InvalidMethod Class

The InvalidMethod class extends the RuntimeException class

Unexpected method call error

 

The NotInitialized Class

The NotInitialized class extends the RuntimeException class
Job Queue is not initialized

 

The NetworkError Class

The NetworkError class extends the RuntimeException class

Network error when communicating with the ZendHQ daemon

 

The Timeout Class

The Timeout class extends the RuntimeException class

Operation timed out

 

The ServerError Class

The ServerError class extends the RuntimeException class

Unclassified server error

 

The LicenseError Class

The LicenceError class extends the RuntimeException class

No valid ZendHQ license or the license is expired

 

The Other Class

The Other class extends the RuntimeException class

Other unclassified errors