PHP API reference - ZendHQ JobQueue

This topic lists the PHP API functions of the ZendHQ JobQueue.

ZendHQ\JobQueue namespace

The Job class

The Job class is used to get information about jobs and queues.

Job methods

Job constants

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:

• There is no connection to the ZendHQ daemon

• There was a failure to communicate with the ZendHQ daemon

• If errors occurred when parsing the message

@throws InvalidArgument if:

• There is no such job.

The CLIJob class

Implements JobDefinition

CLIJob methods

__construct

Throws InvalidArgument if:

• 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: backslash (\), space ( ), double quote ("), and single quote ('), are removed, and the following character preserves its literal value; backslashes preceding characters without special meaning are left unmodified.

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

• Enclosing characters in double quotes (") preserves the literal value of each character within the quotes, with the exception of backslash (\); a double quote (") can be quoted within double quotes by preceding it with a backslash.

getName

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

setName

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

Return value: CLIJob - self

setEnv

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

Return value: CLIJob - self

getEnv

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

getCommand

Return value: string - the full command line

The HTTPJob class

Implements JobDefinition.

HTTPJob methods

HTTPJob constants

__construct

Throws InvalidArgument if:

• $url is not a valid URL

• $method is not one of GET, POST, or PUT

• $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

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

Return value: HTTPJob - self

setURL

Throws InvalidArgument if:

• $url is not a valid URL

Return value: HTTPJob - self

setMethod

Throws InvalidArgument if:

• $method is not one of GET, POST, or PUT

Return value: HTTPJob - self

setContentType

Throws InvalidArgument if:

• $contentType is not a valid value

Return value: HTTPJob - self

addHeader

Return value: HTTPJob - self

addQueryStringArgument

Return value: HTTPJob - self

addBodyParam

Throws InvalidMethod if:

• method is GET

• addRawBody() is already called

Return value: HTTPJob - self

setRawBody

Throws InvalidMethod if:

• method is GET

• 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:

• job is not queued yet and the body is 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

getName

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

setName

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

Return value: JobDefinition - self

The JobOptions class

JobOptions methods

JobOptions constants

__construct

Throws InvalidArgument if:

• $priority value is not valid

• $timeout is <= 0 or $timeout > 2147483

• $allowedRetries < 0

• $retryWaitTime < 0 or $retryWaitTime > 2147483

• $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

Throws InvalidArgument if:

• the $priority value is invalid

Return value: JobOptions - self

setTimeout

Throws InvalidArgument if:

• $seconds <= 0 or $seconds > 2147483

Return value: JobOptions - self

setAllowedRetries

Throws InvalidArgument if:

• $retries < 0

Return value: JobOptions - self

setRetryWaitTime

Throws InvalidArgument if:

• $seconds <= 0 or $seconds > 2147483

Return value: JobOptions - self

setPersistOutput

Throws InvalidArgument if:

• the $persist value is invalid

Return value: JobOptions - self

validateSsl

Return value: JobOptions - self

The JobQueue class

JobQueue methods

__construct

Throws InvalidArgument if:

• the optional 0mq $endpoint is invalid

Throws NetworkError if:

• failed to connect to the ZendHQ daemon

• protocol mismatch (daemon and extension versions are different)

• message parsing errors

Throws LicenseError if:

• ZendHQ license is missing, invalid, or expired

If the $endpoint parameter is omitted, then the system 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:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

getDefaultQueue

Return value: Queue - the default JobQueue queue

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

Throws ServerError if:

• ZendHQ daemon did not respond with a valid queue

getQueue

Return value: Queue - The queue

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

Throws InvalidArgument if:

• no queue with the given $queueName

Throws ServerError if:

• ZendHQ daemon did not respond with a valid queue

hasQueue

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

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

Throws ServerError if:

• ZendHQ daemon did not respond with a valid queue

addQueue

Return value: Queue - The added queue instance

Throws InvalidArgument if:

• queue name is empty or longer than 256 characters

• a queue with the given name already exists

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

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

modifyQueue

Return value: Queue - The modified queue instance

Throws InvalidArgument if:

• the queue does not exist

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

deleteQueue

Throws InvalidArgument if:

• the queue does not exist

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

Throws ServerError if:

• the queue is not suspended

The queue MUST be suspended before it can be deleted.

The Queue class

Queue methods

Queue constants

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:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

suspend

Return value: void

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

Throws Timeout if:

• the queue did not suspend within the specified time

If the $timeout argument is zero, then the system returns immediately after sending the request to the ZendHQ daemon without waiting.

resume

Return value: void

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

Throws Timeout if:

• the queue did not resume within the specified time

If the $timeout argument is zero, then the system 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:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

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

getJobsByName

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

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

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

getJob

Return value: Job - The job instance

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

Throws InvalidArgument if:

• no job with the given $id

Throws ServerError if:

• ZendHQ daemon didn't respond with a valid job

scheduleJob

Return value: Job - The scheduled job

Throws NotInitialized if:

• the Queue object is not associated with any JobQueue objects

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

Throws ServerError if:

• 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 the system schedules the job for immediate execution.

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

cancelJob

Return value: void

Throws NetworkError if:

• not connected to ZendHQ daemon

• failed to communicate with the ZendHQ daemon

• message parsing errors

Throws InvalidArgument if:

• the $job object is not valid

• 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 the system marks it as unknown (Job::STATUS_UNKNOWN)

The QueueDefinition class

QueueDefinition methods

__construct

Throws InvalidArgument if:

• the $priority value is invalid

JobQueue 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

Throws InvalidArgument if:

• the $priority value is invalid

Return value: QueueDefinition - self

setDefaultJobOptions

Return value: QueueDefinition - self

The RecurringSchedule class

The RecurringSchedule class implements the Schedule interface

RecurringSchedule methods

__construct

Throws InvalidArgument if:

• the $crontab string is invalid

getSchedule

Return value: string - Schedule

The Schedule interface

Schedule methods

getSchedule

Return value: mixed

The ScheduledTime class

The RecurringSchedule class implements the Schedule interface

ScheduledTime methods

__construct

Throws InvalidArgument if:

• 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
JobQueue 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