Documentation

Job
in package
Uses UtilsProvider

A job model.

Table of Contents

Constants

DEFAULT_PRIORITY  = 10
RECURRING_EXCEPTION_CODE  = 'queue_paused_previous_failed'
RECURRING_EXCEPTION_ITEMS  = 4
If x jobs of the same type fails, pause all other jobs to avoid unnecessary executions.
WORKER_CLIENT  = 'client'
WORKER_SERVER  = 'server'

Properties

$callable  : callable
The callable for this job.
$capability  : string|null
Capability needed for this job to run.
$created  : string
Created time as ISO string.
$data  : mixed
A `json_encode`able object which gets persisted for this job which you can use in your executor.
$delay_ms  : int
How long should be waited until the next job can be passed to the executor?
$duration_ms  : int
The duration took to complete this task.
$exception  : null|WP_Error
Exception caused by this job. This automatically pauses the complete queue.
$group_position  : int
The jobs' position within this group.
$group_total  : int
Due to the fact we have a garbage collection of jobs in our database table, but we want to keep track of the total items within this group (e.g. Website scanner = Total sites to scan).
$group_uuid  : string
Do not use this manually! See `Persist::startGroup`.
$id  : int
ID.
$lock_until  : int
Timestamp at which this job can be picked again.
$locked  : bool
Is this job currently processing?
$priority  : int
Priority of this job. A lower priority means the job gets executed earlier.
$process  : int
Describe the process for this job. So you could iteratively work at this job within different executions.
$process_total  : int
The total process needed of `process` to consider this job as `done`.
$retries  : int
How often should the job be retried when failure before stopping the complete queue and show an error message?
$runs  : int
Shows, how often this job has been run already. This is needed for `retries`. You do not have to fill this!
$type  : string
The type describes the unique type of this job. Something like `rpm-move-file` (with a prefix of your plugin).
$worker  : string
Where should this job be executed? Default is `server`. If you set this to `client` you need to manually resolve this job as done in your frontend coding (e.g. extra request).
$breakRun  : bool
Indicates, when this job got run and wants to wait for the next execution (e.g. through REST API request) instead of blocking the current PHP thread again. This only works for `server` worker and when the job ran successfully.
$core  : mixed
$updatedJobsToAvoidRecurringException  : bool
Indicates, when run this job a recurring got detected and jobs got paused automatically.

Methods

__construct()  : mixed
C'tor.
actions()  : mixed
See filter `DevOwl/RealQueue/Job/Actions`.
breakRun()  : mixed
Break the current run and wait for the next execution (e.g. through REST API request).
execute()  : void|WP_Error
Execute this job on our server.
getPluginConstantPrefix()  : string
Get the prefix of this package so we can utils package natively.
hasUpdatedJobsToAvoidRecurringException()  : mixed
Getter.
isBreakRun()  : mixed
Check if the current run got broken.
isDone()  : mixed
Check if the job is already done?
isLastInGroup()  : mixed
Check if this job is the last in this group?
label()  : mixed
See filter `DevOwl/RealQueue/Job/Label`.
omitClientData()  : mixed
Omit client data e.g. `data` of server-worker and `callable`.
passthruClientResult()  : mixed
Save the state of the client worker result.
set_error_handler()  : mixed
Set error handler.
setupConstants()  : mixed
Make sure the REAL_QUEUE constants are available.
updatedLocked()  : mixed
Update `locked` attribute so jobs are not executed twice.
updateException()  : mixed
Update `exception` and mark the job as failed. This causes the complete queue to be paused.
updateProcess()  : mixed
Update `process` and mark the job as in progress or done.
avoidRecurringException()  : mixed
When a job fails, check if jobs from the same type failed a few times before, too.
cumulateDuration()  : mixed
Update `duration`.
updateRuns()  : mixed
Update `runs` so `retries` works as expected.

Constants

DEFAULT_PRIORITY

public mixed DEFAULT_PRIORITY = 10

RECURRING_EXCEPTION_CODE

public mixed RECURRING_EXCEPTION_CODE = 'queue_paused_previous_failed'

RECURRING_EXCEPTION_ITEMS

If x jobs of the same type fails, pause all other jobs to avoid unnecessary executions.

public mixed RECURRING_EXCEPTION_ITEMS = 4

A UI dialog needs to be shown to the user so the user can decide to repeat or delete jobs.

WORKER_CLIENT

public mixed WORKER_CLIENT = 'client'

WORKER_SERVER

public mixed WORKER_SERVER = 'server'

Properties

$callable

The callable for this job.

public callable $callable

Attention: If you are using a client-worker, you need to register a custom event, see also CLIENT_JOB_EVENT_PREFIX for more information!

Please note the following things:

  • This field is only needed for server worker
  • You are not allowed to use object instances; only static methods or functions!
  • The callable gets one parameter: Job $job
  • You need to $job->updateProcess() to mark the job as in progress or done!
  • Your callable can throw an Exception or return a WP_Error instance
  • Your callable should be save to be also executed by users with minimal capabilities
  • You are allowed to modify the job data and when the job is run successfully, the changes are persisted

$created

Created time as ISO string.

public string $created

$data

A `json_encode`able object which gets persisted for this job which you can use in your executor.

public mixed $data

If you set keepClientData to true, the data will not be omitted when sending the job to the client.

$delay_ms

How long should be waited until the next job can be passed to the executor?

public int $delay_ms = 1000

$duration_ms

The duration took to complete this task.

public int $duration_ms

$exception

Exception caused by this job. This automatically pauses the complete queue.

public null|WP_Error $exception

$group_position

The jobs' position within this group.

public int $group_position

$group_total

Due to the fact we have a garbage collection of jobs in our database table, but we want to keep track of the total items within this group (e.g. Website scanner = Total sites to scan).

public int $group_total

$group_uuid

Do not use this manually! See `Persist::startGroup`.

public string $group_uuid

$id

ID.

public int $id

$lock_until

Timestamp at which this job can be picked again.

public int $lock_until

$locked

Is this job currently processing?

public bool $locked

$priority

Priority of this job. A lower priority means the job gets executed earlier.

public int $priority = self::DEFAULT_PRIORITY

$process

Describe the process for this job. So you could iteratively work at this job within different executions.

public int $process = 0

$process_total

The total process needed of `process` to consider this job as `done`.

public int $process_total = 1

$retries

How often should the job be retried when failure before stopping the complete queue and show an error message?

public int $retries = 0

$runs

Shows, how often this job has been run already. This is needed for `retries`. You do not have to fill this!

public int $runs = 0

$type

The type describes the unique type of this job. Something like `rpm-move-file` (with a prefix of your plugin).

public string $type

$worker

Where should this job be executed? Default is `server`. If you set this to `client` you need to manually resolve this job as done in your frontend coding (e.g. extra request).

public string $worker = self::WORKER_SERVER

Client-Worker:

  • You need to register your callable via JavaScript function: exposeCallable()
  • You need to manually expose a REST API call so you can update the job with passthruClientResult()
  • You can run into multiple executions for client-tasks, expect you do an explicit locked check before starting the expensive task
    • You can also avoid this, e.g. when you send the results of the client-worked task to the PHP client -> check if the job got already processed by another tab.

Please use WORKER_ constants.

$breakRun

Indicates, when this job got run and wants to wait for the next execution (e.g. through REST API request) instead of blocking the current PHP thread again. This only works for `server` worker and when the job ran successfully.

private bool $breakRun = false

$core

private mixed $core

$updatedJobsToAvoidRecurringException

Indicates, when run this job a recurring got detected and jobs got paused automatically.

private bool $updatedJobsToAvoidRecurringException = false

Methods

__construct()

C'tor.

public __construct(Core $core) : mixed
Parameters
$core : Core

actions()

See filter `DevOwl/RealQueue/Job/Actions`.

public static actions(string $type) : mixed
Parameters
$type : string

breakRun()

Break the current run and wait for the next execution (e.g. through REST API request).

public breakRun() : mixed

execute()

Execute this job on our server.

public execute() : void|WP_Error
Return values
void|WP_Error

getPluginConstantPrefix()

Get the prefix of this package so we can utils package natively.

public getPluginConstantPrefix() : string
Return values
string

hasUpdatedJobsToAvoidRecurringException()

Getter.

public hasUpdatedJobsToAvoidRecurringException() : mixed

isBreakRun()

Check if the current run got broken.

public isBreakRun() : mixed

isDone()

Check if the job is already done?

public isDone() : mixed

isLastInGroup()

Check if this job is the last in this group?

public isLastInGroup() : mixed

label()

See filter `DevOwl/RealQueue/Job/Label`.

public static label(string $type) : mixed
Parameters
$type : string

omitClientData()

Omit client data e.g. `data` of server-worker and `callable`.

public omitClientData() : mixed

passthruClientResult()

Save the state of the client worker result.

public passthruClientResult(int|true $process, WP_Error|null $error) : mixed
Parameters
$process : int|true
$error : WP_Error|null

setupConstants()

Make sure the REAL_QUEUE constants are available.

public static setupConstants() : mixed

updatedLocked()

Update `locked` attribute so jobs are not executed twice.

public updatedLocked(bool $locked) : mixed
Parameters
$locked : bool

updateException()

Update `exception` and mark the job as failed. This causes the complete queue to be paused.

public updateException(WP_Error|null $error) : mixed
Parameters
$error : WP_Error|null

updateProcess()

Update `process` and mark the job as in progress or done.

public updateProcess(int|true $process[, int $process_total = null ]) : mixed
Parameters
$process : int|true
$process_total : int = null

avoidRecurringException()

When a job fails, check if jobs from the same type failed a few times before, too.

protected avoidRecurringException() : mixed

If yes, update runs and set an exception that signals a paused queue.

cumulateDuration()

Update `duration`.

protected cumulateDuration(int|float $start) : mixed
Parameters
$start : int|float

microtime(true) before you do something heavy

updateRuns()

Update `runs` so `retries` works as expected.

protected updateRuns(int $previousProcess[, int $force = null ]) : mixed
Parameters
$previousProcess : int
$force : int = null 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results