Documentation

Job extends AbstractJob
in package

Job class

Tags
category

Pop

author

Nick Sagona, III nick@popphp.org

copyright

Copyright (c) 2009-2026 Nick Sagona, III

license

https://www.popphp.org/license New BSD License

version
3.0.0

Table of Contents

Properties

$attempts  : int
Attempts
$availableAt  : int|null
Timestamp before which this job is not eligible for reservation
$backoff  : int|array<string|int, mixed>|null
Retry backoff: a fixed delay in seconds, or a per-attempt schedule that holds at its last value for further attempts. Null = immediate retry.
$callable  : CallableObject|null
Job callable
$command  : string|array<string|int, mixed>|null
Job application command - an invocation string routed through the application (e.g. 'greet Nick'), or an argv-style array of already split segments (e.g. ['notify', 'Hello there, world']). The string form is split on whitespace by the router, so the array form is the only way to pass a value that itself contains spaces.
$completed  : int|null
Job completed timestamp
$description  : string|null
Job Description
$exec  : string|array<string|int, mixed>|null
Job CLI executable command - a shell command string (runs via the shell, e.g. 'ls -la | wc -l'), or an argv-style array to run with no shell involved at all (e.g. ['ls', '-la'] - the safer form when any part of the command isn't a fully-trusted literal, since shell metacharacters in an argv element are inert)
$failed  : int|null
Job failed timestamp
$failedMessages  : array<string|int, mixed>
Job failed messages
$id  : string|null
Job ID
$maxAttempts  : int
Max attempts
$results  : mixed
Job results
$runUntil  : int|string|null
Run until property
$serializedClosure  : string|null
Serialize closure
$serializedParameters  : array<string|int, mixed>|null
Serialize parameters
$started  : int|null
Job started timestamp
$timeout  : int|null
Soft execution timeout, in seconds (only enforced when ext-pcntl is loaded)

Methods

__construct()  : mixed
Constructor
__sleep()  : array<string|int, mixed>
Sleep magic method
__wakeup()  : void
Wakeup magic method
addFailedMessage()  : AbstractJob
Add failed message
command()  : static
Create a job object with an application command - an invocation string routed through the application (e.g. Job::command('greet Nick')), or an argv-style array of already split segments (e.g.
complete()  : AbstractJob
Complete job
create()  : Job
Create job
delay()  : AbstractJob
Delay job availability
exec()  : static
Create a job object with a CLI executable command - a shell command string (runs via the shell, e.g. Job::exec('ls -la | wc -l')), or an argv-style array to run with no shell involved at all (e.g.
failed()  : AbstractJob
Set job as failed
generateJobId()  : string
Generate job ID
getAttempts()  : int
Get actual attempts
getAvailableAt()  : int|null
Get available-at timestamp
getBackoff()  : int|array<string|int, mixed>|null
Get retry backoff
getBackoffDelay()  : int
Get the backoff delay, in seconds, for the current attempt count
getCallable()  : CallableObject|null
Get job callable
getCommand()  : string|array<string|int, mixed>|null
Get job application command
getCompleted()  : int|null
Get completed timestamp
getDuration()  : int|null
Get how long the job took to run, in seconds, or null unless it both started and completed. Convenience for observability listeners, which would otherwise all repeat the same timestamp subtraction.
getExec()  : string|array<string|int, mixed>|null
Get job CLI executable command
getFailed()  : int|null
Get failed timestamp
getFailedMessages()  : array<string|int, mixed>
Get failed messages
getJobDescription()  : string|null
Get job description
getJobId()  : string|null
Get job ID
getMaxAttempts()  : int
Get max attempts
getResults()  : mixed
Get job results
getRunUntil()  : int|string|null
Get run until value
getStarted()  : int|null
Get started timestamp
getTimeout()  : int|null
Get soft execution timeout
hasAttempts()  : bool
Has actual attempts
hasBackoff()  : bool
Has retry backoff
hasCallable()  : bool
Has job callable
hasCommand()  : bool
Has job application command
hasExceededMaxAttempts()  : bool
Determine if the job has exceeded max attempts
hasExec()  : bool
Has job CLI executable command
hasFailed()  : bool
Has job failed
hasFailedMessages()  : bool
Has failed messages
hasJobDescription()  : bool
Has job description
hasJobId()  : bool
Has job ID
hasMaxAttempts()  : bool
Has max attempts
hasNotRun()  : bool
Has job run yet
hasResults()  : bool
Has job results
hasRunUntil()  : bool
Has run until
hasStarted()  : bool
Has job started
hasTimeout()  : bool
Has soft execution timeout
isAttemptOnce()  : bool
Is job set for only one max attempt
isAvailable()  : bool
Determine if the job is currently available (no delay, or delay has elapsed)
isComplete()  : bool
Is job complete
isExpired()  : bool
Determine if the job has expired
isRunning()  : bool
Is job running and has not completed or failed yet
isValid()  : bool
Determine if the job is still valid
run()  : mixed
Run job
runUntil()  : AbstractJob
Set the run until property
setBackoff()  : AbstractJob
Set retry backoff (fixed seconds, or a per-attempt schedule)
setCallable()  : AbstractJob
Set job callable
setCommand()  : AbstractJob
Set job application command
setExec()  : AbstractJob
Set job CLI executable command
setJobDescription()  : AbstractJob
Set job description
setJobId()  : AbstractJob
Set job ID
setMaxAttempts()  : AbstractJob
Set max attempts
setTimeout()  : AbstractJob
Set soft execution timeout
start()  : AbstractJob
Start job
buildExecProcess()  : Process
Build the Process instance for this job's exec command, without running it. Split out from runExec() purely so a test can construct one and inspect its configured timeout directly, without actually executing a command.
describeFromCommand()  : void
Borrow a job description from the dispatched command, if it has one and the job was not given one explicitly. A command already documents itself, so a queued command job need not be anonymous in the registry.
loadCallable()  : mixed
Load callable
runCommand()  : mixed
Run application command
runExec()  : mixed
Run CLI executable command

Properties

$availableAt

Timestamp before which this job is not eligible for reservation

protected int|null $availableAt = null

$backoff

Retry backoff: a fixed delay in seconds, or a per-attempt schedule that holds at its last value for further attempts. Null = immediate retry.

protected int|array<string|int, mixed>|null $backoff = null

$command

Job application command - an invocation string routed through the application (e.g. 'greet Nick'), or an argv-style array of already split segments (e.g. ['notify', 'Hello there, world']). The string form is split on whitespace by the router, so the array form is the only way to pass a value that itself contains spaces.

protected string|array<string|int, mixed>|null $command = null

$completed

Job completed timestamp

protected int|null $completed = null

$description

Job Description

protected string|null $description = null

$exec

Job CLI executable command - a shell command string (runs via the shell, e.g. 'ls -la | wc -l'), or an argv-style array to run with no shell involved at all (e.g. ['ls', '-la'] - the safer form when any part of the command isn't a fully-trusted literal, since shell metacharacters in an argv element are inert)

protected string|array<string|int, mixed>|null $exec = null

$failed

Job failed timestamp

protected int|null $failed = null

$failedMessages

Job failed messages

protected array<string|int, mixed> $failedMessages = []

$maxAttempts

Max attempts

protected int $maxAttempts = 0

$results

Job results

protected mixed $results = null

$runUntil

Run until property

protected int|string|null $runUntil = null

$serializedClosure

Serialize closure

protected string|null $serializedClosure = null

$serializedParameters

Serialize parameters

protected array<string|int, mixed>|null $serializedParameters = null

$started

Job started timestamp

protected int|null $started = null

$timeout

Soft execution timeout, in seconds (only enforced when ext-pcntl is loaded)

protected int|null $timeout = null

Methods

__construct()

Constructor

public __construct([mixed $callable = null ][, mixed $params = null ][, string|null $id = null ]) : mixed

Instantiate the job object

Parameters
$callable : mixed = null
$params : mixed = null
$id : string|null = null

__sleep()

Sleep magic method

public __sleep() : array<string|int, mixed>
Return values
array<string|int, mixed>

__wakeup()

Wakeup magic method

public __wakeup() : void

command()

Create a job object with an application command - an invocation string routed through the application (e.g. Job::command('greet Nick')), or an argv-style array of already split segments (e.g.

public static command(string|array<string|int, mixed> $command[, string|null $id = null ]) : static

Job::command(['notify', 'Hello there, world'])). The router splits the string form on whitespace, so the array form is the only way to pass an argument value that itself contains spaces.

Parameters
$command : string|array<string|int, mixed>
$id : string|null = null
Return values
static

create()

Create job

public static create([mixed $callable = null ][, mixed $params = null ][, string|null $id = null ]) : Job
Parameters
$callable : mixed = null
$params : mixed = null
$id : string|null = null
Return values
Job

delay()

Delay job availability

public delay(int|string $when) : AbstractJob
Parameters
$when : int|string

Seconds from now (int below 1000000000), an absolute timestamp (int), or a strtotime()-parseable string

Tags
throws
Exception
Return values
AbstractJob

exec()

Create a job object with a CLI executable command - a shell command string (runs via the shell, e.g. Job::exec('ls -la | wc -l')), or an argv-style array to run with no shell involved at all (e.g.

public static exec(string|array<string|int, mixed> $command[, string|null $id = null ]) : static

Job::exec(['ls', '-la']) - the safer form when any part of the command isn't a fully-trusted literal, since shell metacharacters in an argv element are inert)

Parameters
$command : string|array<string|int, mixed>
$id : string|null = null
Return values
static

generateJobId()

Generate job ID

public generateJobId() : string
Return values
string

getAttempts()

Get actual attempts

public getAttempts() : int
Return values
int

getAvailableAt()

Get available-at timestamp

public getAvailableAt() : int|null
Return values
int|null

getBackoff()

Get retry backoff

public getBackoff() : int|array<string|int, mixed>|null
Return values
int|array<string|int, mixed>|null

getBackoffDelay()

Get the backoff delay, in seconds, for the current attempt count

public getBackoffDelay() : int
Return values
int

getCommand()

Get job application command

public getCommand() : string|array<string|int, mixed>|null
Return values
string|array<string|int, mixed>|null

getCompleted()

Get completed timestamp

public getCompleted() : int|null
Return values
int|null

getDuration()

Get how long the job took to run, in seconds, or null unless it both started and completed. Convenience for observability listeners, which would otherwise all repeat the same timestamp subtraction.

public getDuration() : int|null
Return values
int|null

getExec()

Get job CLI executable command

public getExec() : string|array<string|int, mixed>|null
Return values
string|array<string|int, mixed>|null

getFailed()

Get failed timestamp

public getFailed() : int|null
Return values
int|null

getFailedMessages()

Get failed messages

public getFailedMessages() : array<string|int, mixed>
Return values
array<string|int, mixed>

getJobDescription()

Get job description

public getJobDescription() : string|null
Return values
string|null

getJobId()

Get job ID

public getJobId() : string|null
Return values
string|null

getMaxAttempts()

Get max attempts

public getMaxAttempts() : int
Return values
int

getResults()

Get job results

public getResults() : mixed

getRunUntil()

Get run until value

public getRunUntil() : int|string|null
Return values
int|string|null

getStarted()

Get started timestamp

public getStarted() : int|null
Return values
int|null

getTimeout()

Get soft execution timeout

public getTimeout() : int|null
Return values
int|null

hasAttempts()

Has actual attempts

public hasAttempts() : bool
Return values
bool

hasBackoff()

Has retry backoff

public hasBackoff() : bool
Return values
bool

hasCallable()

Has job callable

public hasCallable() : bool
Return values
bool

hasCommand()

Has job application command

public hasCommand() : bool
Return values
bool

hasExceededMaxAttempts()

Determine if the job has exceeded max attempts

public hasExceededMaxAttempts() : bool
Return values
bool

hasExec()

Has job CLI executable command

public hasExec() : bool
Return values
bool

hasFailed()

Has job failed

public hasFailed() : bool
Return values
bool

hasFailedMessages()

Has failed messages

public hasFailedMessages() : bool
Return values
bool

hasJobDescription()

Has job description

public hasJobDescription() : bool
Return values
bool

hasJobId()

Has job ID

public hasJobId() : bool
Return values
bool

hasMaxAttempts()

Has max attempts

public hasMaxAttempts() : bool
Return values
bool

hasNotRun()

Has job run yet

public hasNotRun() : bool
Return values
bool

hasResults()

Has job results

public hasResults() : bool
Return values
bool

hasRunUntil()

Has run until

public hasRunUntil() : bool
Return values
bool

hasStarted()

Has job started

public hasStarted() : bool
Return values
bool

hasTimeout()

Has soft execution timeout

public hasTimeout() : bool
Return values
bool

isAttemptOnce()

Is job set for only one max attempt

public isAttemptOnce() : bool
Return values
bool

isAvailable()

Determine if the job is currently available (no delay, or delay has elapsed)

public isAvailable() : bool
Return values
bool

isComplete()

Is job complete

public isComplete() : bool
Return values
bool

isExpired()

Determine if the job has expired

public isExpired() : bool
Return values
bool

isRunning()

Is job running and has not completed or failed yet

public isRunning() : bool
Return values
bool

isValid()

Determine if the job is still valid

public isValid() : bool

Impure on two counts: it reads $attempts, which failed() increments, and it compares $runUntil against the current time. The same job can answer true and then false without anything being reassigned, so callers must not have an earlier answer cached on their behalf.

Tags
phpstan-impure
Return values
bool

setBackoff()

Set retry backoff (fixed seconds, or a per-attempt schedule)

public setBackoff(int|array<string|int, mixed> $backoff) : AbstractJob
Parameters
$backoff : int|array<string|int, mixed>
Return values
AbstractJob

setCallable()

Set job callable

public setCallable(mixed $callable[, mixed $params = null ]) : AbstractJob
Parameters
$callable : mixed
$params : mixed = null
Return values
AbstractJob

setCommand()

Set job application command

public setCommand(string|array<string|int, mixed> $command) : AbstractJob
Parameters
$command : string|array<string|int, mixed>
Return values
AbstractJob

setExec()

Set job CLI executable command

public setExec(string|array<string|int, mixed> $command) : AbstractJob
Parameters
$command : string|array<string|int, mixed>
Return values
AbstractJob

buildExecProcess()

Build the Process instance for this job's exec command, without running it. Split out from runExec() purely so a test can construct one and inspect its configured timeout directly, without actually executing a command.

protected buildExecProcess() : Process
Return values
Process

describeFromCommand()

Borrow a job description from the dispatched command, if it has one and the job was not given one explicitly. A command already documents itself, so a queued command job need not be anonymous in the registry.

protected describeFromCommand(mixed $dispatchable) : void

Guarded by instanceof rather than a hard dependency: pop-console arrives transitively through popphp, and instanceof against a missing class is simply false rather than an error.

Parameters
$dispatchable : mixed

runExec()

Run CLI executable command

protected runExec() : mixed
Tags
throws
ProcessFailedException|ProcessTimedOutException 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results