BC Migration Documentation

WP_Background_Process extends WP_Async_Request
in package

AbstractYes

Abstract WP_Background_Process class.

Tags
abstract
@extends

WP_Async_Request

Table of Contents

Constants

STATUS_CANCELLED  = 1
The status set when process is cancelling.
STATUS_PAUSED  = 2
The status set when process is paused or pausing.

Properties

$action  : string
Action
$allowed_batch_data_classes  : bool|array<string|int, mixed>
Restrict object instantiation when using unserialize.
$cron_hook_identifier  : string
Cron_hook_identifier
$cron_interval_identifier  : string
Cron_interval_identifier
$data  : array<string|int, mixed>
Data
$identifier  : mixed
Identifier
$prefix  : string
Prefix
$start_time  : int
Start time of current process.

Methods

__construct()  : mixed
Initiate new background process.
cancel()  : mixed
Cancel job on next batch.
cancel_process()  : mixed
Cancel the background process.
data()  : $this
Set data used during the request.
delete()  : $this
Delete a batch of queued items.
delete_all()  : mixed
Delete entire job queue.
dispatch()  : array<string|int, mixed>|WP_Error|false
Schedule the cron healthcheck and dispatch an async request to start processing the queue.
get_batches()  : array<string|int, mixed>
Get batches.
get_cron_interval()  : int
Get the cron healthcheck interval in minutes.
handle_cron_healthcheck()  : mixed
Handle cron healthcheck event.
is_active()  : bool
Is the tool currently active, e.g. starting, working, paused or cleaning up?
is_cancelled()  : bool
Has the process been cancelled?
is_paused()  : bool
Is the job paused?
is_processing()  : bool
Is the background process currently running?
is_queued()  : bool
Is queued?
maybe_handle()  : void|mixed
Maybe process a batch of queued items.
pause()  : mixed
Pause job on next batch.
push_to_queue()  : $this
Push to the queue.
resume()  : mixed
Resume job.
save()  : $this
Save the queued items for future processing.
schedule_cron_healthcheck()  : mixed
Schedule the cron healthcheck job.
update()  : $this
Update a batch's queued items.
cancelled()  : mixed
Called when background process has been cancelled.
clear_scheduled_event()  : mixed
Clear scheduled cron healthcheck event.
complete()  : mixed
Complete processing.
completed()  : mixed
Called when background process has completed.
generate_key()  : string
Generate key for a batch.
get_batch()  : stdClass
Get batch.
get_memory_limit()  : int
Get memory limit in bytes.
get_post_args()  : array<string|int, mixed>
Get post args.
get_query_args()  : array<string|int, mixed>
Get query args.
get_query_url()  : string
Get query URL.
get_status_key()  : string
Get the status key.
handle()  : mixed
Handle a dispatched request.
is_process_running()  : bool
Is process running?
is_queue_empty()  : bool
Is queue empty?
lock_process()  : mixed
Lock process.
maybe_unserialize()  : mixed
Maybe unserialize data, but not if an object.
maybe_wp_die()  : void|mixed
Should the process exit with wp_die?
memory_exceeded()  : bool
Memory exceeded?
paused()  : mixed
Called when background process has been paused.
resumed()  : mixed
Called when background process has been resumed.
schedule_event()  : mixed
Schedule the cron healthcheck event.
task()  : mixed
Perform task with queued item.
time_exceeded()  : bool
Time limit exceeded?
unlock_process()  : $this
Unlock process.

Constants

STATUS_PAUSED

The status set when process is paused or pausing.

public mixed STATUS_PAUSED = 2
Tags
@var

int;

Properties

$action

Action

protected string $action = 'background_process'

(default value: 'background_process')

Tags
access

protected

$allowed_batch_data_classes

Restrict object instantiation when using unserialize.

protected bool|array<string|int, mixed> $allowed_batch_data_classes = true

$cron_hook_identifier

Cron_hook_identifier

protected string $cron_hook_identifier
Tags
access

protected

$cron_interval_identifier

Cron_interval_identifier

protected string $cron_interval_identifier
Tags
access

protected

$data

Data

protected array<string|int, mixed> $data = array()

(default value: array())

Tags
access

protected

$identifier

Identifier

protected mixed $identifier
Tags
access

protected

$prefix

Prefix

protected string $prefix = 'wp'

(default value: 'wp')

Tags
access

protected

$start_time

Start time of current process.

protected int $start_time = 0

(default value: 0)

Tags
access

protected

Methods

__construct()

Initiate new background process.

public __construct([bool|array<string|int, mixed> $allowed_batch_data_classes = true ]) : mixed
Parameters
$allowed_batch_data_classes : bool|array<string|int, mixed> = true

Optional. Array of class names that can be unserialized. Default true (any class).

cancel_process()

Cancel the background process.

public cancel_process() : mixed

Superseded.

Stop processing queue items, clear cron job and delete batch.

Tags
see
cancel()

data()

Set data used during the request.

public data(array<string|int, mixed> $data) : $this
Parameters
$data : array<string|int, mixed>

Data.

Return values
$this

delete()

Delete a batch of queued items.

public delete(string $key) : $this
Parameters
$key : string

Key.

Return values
$this

dispatch()

Schedule the cron healthcheck and dispatch an async request to start processing the queue.

public dispatch() : array<string|int, mixed>|WP_Error|false
Tags
access

public

Return values
array<string|int, mixed>|WP_Error|false —

HTTP Response array, WP_Error on failure, or false if not attempted.

get_batches()

Get batches.

public get_batches([int $limit = 0 ]) : array<string|int, mixed>
Parameters
$limit : int = 0

Number of batches to return, defaults to all.

Return values
array<string|int, mixed> —

of stdClass

get_cron_interval()

Get the cron healthcheck interval in minutes.

public get_cron_interval() : int

Default is 5 minutes, minimum is 1 minute.

Return values
int

handle_cron_healthcheck()

Handle cron healthcheck event.

public handle_cron_healthcheck() : mixed

Restart the background process if not already running and data exists in the queue.

is_active()

Is the tool currently active, e.g. starting, working, paused or cleaning up?

public is_active() : bool
Return values
bool

is_cancelled()

Has the process been cancelled?

public is_cancelled() : bool
Return values
bool

is_processing()

Is the background process currently running?

public is_processing() : bool
Return values
bool

maybe_handle()

Maybe process a batch of queued items.

public maybe_handle() : void|mixed

Checks whether data exists within the queue and that the process is not already running.

Return values
void|mixed

push_to_queue()

Push to the queue.

public push_to_queue(mixed $data) : $this

Note, save must be called in order to persist queued items to a batch for processing.

Parameters
$data : mixed

Data.

Return values
$this

save()

Save the queued items for future processing.

public save() : $this
Return values
$this

schedule_cron_healthcheck()

Schedule the cron healthcheck job.

public schedule_cron_healthcheck(mixed $schedules) : mixed
Parameters
$schedules : mixed

Schedules.

Tags
access

public

update()

Update a batch's queued items.

public update(string $key, array<string|int, mixed> $data) : $this
Parameters
$key : string

Key.

$data : array<string|int, mixed>

Data.

Return values
$this

cancelled()

Called when background process has been cancelled.

protected cancelled() : mixed

clear_scheduled_event()

Clear scheduled cron healthcheck event.

protected clear_scheduled_event() : mixed

complete()

Complete processing.

protected complete() : mixed

Override if applicable, but ensure that the below actions are performed, or, call parent::complete().

generate_key()

Generate key for a batch.

protected generate_key([int $length = 64 ][, string $key = 'batch' ]) : string

Generates a unique key based on microtime. Queue items are given a unique key so that they can be merged upon save.

Parameters
$length : int = 64

Optional max length to trim key to, defaults to 64 characters.

$key : string = 'batch'

Optional string to append to identifier before hash, defaults to "batch".

Return values
string

get_batch()

Get batch.

protected get_batch() : stdClass
Return values
stdClass —

Return the first batch of queued items.

get_memory_limit()

Get memory limit in bytes.

protected get_memory_limit() : int
Return values
int

get_post_args()

Get post args.

protected get_post_args() : array<string|int, mixed>
Return values
array<string|int, mixed>

get_query_args()

Get query args.

protected get_query_args() : array<string|int, mixed>
Return values
array<string|int, mixed>

get_query_url()

Get query URL.

protected get_query_url() : string
Return values
string

get_status_key()

Get the status key.

protected get_status_key() : string
Return values
string

handle()

Handle a dispatched request.

protected handle() : mixed

Pass each queue item to the task handler, while remaining within server memory and time limit constraints.

is_process_running()

Is process running?

protected is_process_running() : bool

Superseded.

Check whether the current process is already running in a background process.

Tags
see
is_processing()
Return values
bool

lock_process()

Lock process.

protected lock_process() : mixed

Lock the process so that multiple instances can't run simultaneously. Override if applicable, but the duration should be greater than that defined in the time_exceeded() method.

maybe_unserialize()

Maybe unserialize data, but not if an object.

protected static maybe_unserialize(mixed $data, bool|array<string|int, mixed> $allowed_classes) : mixed
Parameters
$data : mixed

Data to be unserialized.

$allowed_classes : bool|array<string|int, mixed>

Array of class names that can be unserialized.

maybe_wp_die()

Should the process exit with wp_die?

protected maybe_wp_die([mixed $return = null ]) : void|mixed
Parameters
$return : mixed = null

What to return if filter says don't die, default is null.

Return values
void|mixed

memory_exceeded()

Memory exceeded?

protected memory_exceeded() : bool

Ensures the batch process never exceeds 90% of the maximum WordPress memory.

Return values
bool

task()

Perform task with queued item.

protected abstract task(mixed $item) : mixed

Override this method to perform any actions required on each queue item. Return the modified item for further processing in the next pass through. Or, return false to remove the item from the queue.

Parameters
$item : mixed

Queue item to iterate over.

time_exceeded()

Time limit exceeded?

protected time_exceeded() : bool

Ensures the batch never exceeds a sensible time limit. A timeout limit of 30s is common on shared hosting.

Return values
bool

unlock_process()

Unlock process.

protected unlock_process() : $this

Unlock the process so that other instances can spawn.

Return values
$this 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results