Documentation

Task extends Job
in package

Task 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
$cron  : Cron|null
The cron Task
$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
between()  : Task
Set job schedule to between two hours
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()  : Task
Create task
cron()  : Cron|null
Get cron Task (alias)
daily()  : Task
Set job schedule to daily
dailyAt()  : Task
Set job schedule to daily at specific time, i.e. 14:30
delay()  : AbstractJob
Delay job availability
every10Minutes()  : Task
Set job schedule to every 10 minutes
every10Seconds()  : Task
Set job schedule to every 10 seconds
every15Minutes()  : Task
Set job schedule to every 15 minutes
every15Seconds()  : Task
Set job schedule to every 15 seconds
every20Minutes()  : Task
Set job schedule to every 20 minutes
every20Seconds()  : Task
Set job schedule to every 20 seconds
every30Minutes()  : Task
Set job schedule to every 30 minutes
every30Seconds()  : Task
Set job schedule to every 30 seconds
every5Minutes()  : Task
Set job schedule to every 5 minutes
every5Seconds()  : Task
Set job schedule to every 5 seconds
everyMinute()  : Task
Set job schedule to every minute
everySecond()  : Task
Set job schedule to every second
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
fridays()  : Task
Set job schedule to Fridays
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
getCron()  : Cron|null
Get cron Task
getDaysOfTheMonth()  : array<string|int, mixed>
Get days of the month
getDaysOfTheWeek()  : array<string|int, mixed>
Get days of the week
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
getGracePeriod()  : int
Get grace period
getHours()  : array<string|int, mixed>
Get hours
getJobDescription()  : string|null
Get job description
getJobId()  : string|null
Get job ID
getMaxAttempts()  : int
Get max attempts
getMinutes()  : array<string|int, mixed>
Get minutes
getMonths()  : array<string|int, mixed>
Get months
getResults()  : mixed
Get job results
getRunUntil()  : int|string|null
Get run until value
getSeconds()  : array<string|int, mixed>
Get seconds
getStarted()  : int|null
Get started timestamp
getTaskId()  : string|null
Get task id (alias)
getTimeout()  : int|null
Get soft execution timeout
gracePeriod()  : Task
Set grace period (alias)
hasAttempts()  : bool
Has actual attempts
hasBackoff()  : bool
Has retry backoff
hasCallable()  : bool
Has job callable
hasCommand()  : bool
Has job application command
hasCron()  : bool
Has cron Task
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
hasGracePeriod()  : bool
Has grace period
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
hasTaskId()  : bool
Has task ID (alias)
hasTimeout()  : bool
Has soft execution timeout
hourly()  : Task
Set job schedule to hourly
hours()  : Task
Set job schedule to by specific hours
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
minutes()  : Task
Set job schedule to by specific minutes
mondays()  : Task
Set job schedule to Mondays
monthly()  : Task
Set job schedule to monthly
quarterly()  : Task
Set job schedule to quarterly
run()  : mixed
Run job
runUntil()  : AbstractJob
Set the run until property
saturdays()  : Task
Set job schedule to Saturdays
schedule()  : Task
Schedule cront
seconds()  : Task
Set job schedule to by specific seconds
setBackoff()  : AbstractJob
Set retry backoff (fixed seconds, or a per-attempt schedule)
setCallable()  : AbstractJob
Set job callable
setCommand()  : AbstractJob
Set job application command
setCron()  : Task
Set cron Task
setExec()  : AbstractJob
Set job CLI executable command
setGracePeriod()  : Task
Set grace period
setJobDescription()  : AbstractJob
Set job description
setJobId()  : AbstractJob
Set job ID
setMaxAttempts()  : AbstractJob
Set max attempts
setTaskId()  : Task
Set task ID (alias)
setTimeout()  : AbstractJob
Set soft execution timeout
start()  : AbstractJob
Start job
sundays()  : Task
Set job schedule to Sundays
thursdays()  : Task
Set job schedule to Thursdays
tuesdays()  : Task
Set job schedule to Tuesdays
wednesdays()  : Task
Set job schedule to Wednesdays
weekdays()  : Task
Set job schedule to weekdays
weekends()  : Task
Set job schedule to weekends
weekly()  : Task
Set job schedule to weekly
yearly()  : Task
Set job schedule to yearly
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

$cron

The cron Task

protected Cron|null $cron = 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 ][, Cron $cron = new Cron() ]) : mixed

Instantiate the job object

Parameters
$callable : mixed = null
$params : mixed = null
$id : string|null = null
$cron : Cron = new Cron()

__sleep()

Sleep magic method

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

__wakeup()

Wakeup magic method

public __wakeup() : void

between()

Set job schedule to between two hours

public between(int $start, int $end) : Task
Parameters
$start : int
$end : int
Return values
Task

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 task

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

cron()

Get cron Task (alias)

public cron() : Cron|null
Return values
Cron|null

daily()

Set job schedule to daily

public daily(mixed $hours[, mixed $minutes = null ]) : Task
Parameters
$hours : mixed
$minutes : mixed = null
Return values
Task

dailyAt()

Set job schedule to daily at specific time, i.e. 14:30

public dailyAt(string $time) : Task
Parameters
$time : string
Return values
Task

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

every10Minutes()

Set job schedule to every 10 minutes

public every10Minutes() : Task
Return values
Task

every10Seconds()

Set job schedule to every 10 seconds

public every10Seconds() : Task
Return values
Task

every15Minutes()

Set job schedule to every 15 minutes

public every15Minutes() : Task
Return values
Task

every15Seconds()

Set job schedule to every 15 seconds

public every15Seconds() : Task
Return values
Task

every20Minutes()

Set job schedule to every 20 minutes

public every20Minutes() : Task
Return values
Task

every20Seconds()

Set job schedule to every 20 seconds

public every20Seconds() : Task
Return values
Task

every30Minutes()

Set job schedule to every 30 minutes

public every30Minutes() : Task
Return values
Task

every30Seconds()

Set job schedule to every 30 seconds

public every30Seconds() : Task
Return values
Task

every5Minutes()

Set job schedule to every 5 minutes

public every5Minutes() : Task
Return values
Task

every5Seconds()

Set job schedule to every 5 seconds

public every5Seconds() : Task
Return values
Task

everyMinute()

Set job schedule to every minute

public everyMinute() : Task
Return values
Task

everySecond()

Set job schedule to every second

public everySecond() : Task
Return values
Task

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

fridays()

Set job schedule to Fridays

public fridays() : Task
Return values
Task

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

getCron()

Get cron Task

public getCron() : Cron|null
Return values
Cron|null

getDaysOfTheMonth()

Get days of the month

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

getDaysOfTheWeek()

Get days of the week

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

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>

getGracePeriod()

Get grace period

public getGracePeriod() : int
Return values
int

getHours()

Get hours

public getHours() : 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

getMinutes()

Get minutes

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

getMonths()

Get months

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

getResults()

Get job results

public getResults() : mixed

getRunUntil()

Get run until value

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

getSeconds()

Get seconds

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

getStarted()

Get started timestamp

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

getTaskId()

Get task id (alias)

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

getTimeout()

Get soft execution timeout

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

gracePeriod()

Set grace period (alias)

public gracePeriod(int $gracePeriod) : Task
Parameters
$gracePeriod : int
Return values
Task

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

hasCron()

Has cron Task

public hasCron() : 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

hasGracePeriod()

Has grace period

public hasGracePeriod() : 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

hasTaskId()

Has task ID (alias)

public hasTaskId() : bool
Return values
bool

hasTimeout()

Has soft execution timeout

public hasTimeout() : bool
Return values
bool

hourly()

Set job schedule to hourly

public hourly([mixed $minutes = null ]) : Task
Parameters
$minutes : mixed = null
Return values
Task

hours()

Set job schedule to by specific hours

public hours(mixed $hours[, mixed $minutes = null ]) : Task
Parameters
$hours : mixed
$minutes : mixed = null
Return values
Task

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

minutes()

Set job schedule to by specific minutes

public minutes(mixed $minutes) : Task
Parameters
$minutes : mixed
Return values
Task

mondays()

Set job schedule to Mondays

public mondays() : Task
Return values
Task

monthly()

Set job schedule to monthly

public monthly(mixed $day[, mixed $hours = null ][, mixed $minutes = null ]) : Task
Parameters
$day : mixed
$hours : mixed = null
$minutes : mixed = null
Return values
Task

quarterly()

Set job schedule to quarterly

public quarterly([mixed $hours = null ][, mixed $minutes = null ]) : Task
Parameters
$hours : mixed = null
$minutes : mixed = null
Return values
Task

saturdays()

Set job schedule to Saturdays

public saturdays() : Task
Return values
Task

schedule()

Schedule cront

public schedule(mixed $schedule) : Task
Parameters
$schedule : mixed
Return values
Task

seconds()

Set job schedule to by specific seconds

public seconds(mixed $seconds) : Task
Parameters
$seconds : mixed
Return values
Task

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

setGracePeriod()

Set grace period

public setGracePeriod(int $gracePeriod) : Task
Parameters
$gracePeriod : int
Return values
Task

setTaskId()

Set task ID (alias)

public setTaskId(string $id) : Task
Parameters
$id : string
Return values
Task

sundays()

Set job schedule to Sundays

public sundays() : Task
Return values
Task

thursdays()

Set job schedule to Thursdays

public thursdays() : Task
Return values
Task

tuesdays()

Set job schedule to Tuesdays

public tuesdays() : Task
Return values
Task

wednesdays()

Set job schedule to Wednesdays

public wednesdays() : Task
Return values
Task

weekdays()

Set job schedule to weekdays

public weekdays() : Task
Return values
Task

weekends()

Set job schedule to weekends

public weekends() : Task
Return values
Task

weekly()

Set job schedule to weekly

public weekly(mixed $day[, mixed $hours = null ][, mixed $minutes = null ]) : Task
Parameters
$day : mixed
$hours : mixed = null
$minutes : mixed = null
Return values
Task

yearly()

Set job schedule to yearly

public yearly([bool $endOfYear = false ][, mixed $hours = null ][, mixed $minutes = null ]) : Task
Parameters
$endOfYear : bool = false
$hours : mixed = null
$minutes : mixed = null
Return values
Task

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