Documentation

Queue extends AbstractQueue
in package

Queue 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

Constants

FIFO  = 'FIFO'
Queue priority constants
FILO  = 'FILO'

Properties

$adapter  : AdapterInterface|TaskAdapterInterface
Queue adapter
$events  : Manager|null
Event manager, for lifecycle observability hooks (queue.job.*, queue.task.*).
$name  : string
Queue name

Methods

__construct()  : mixed
Constructor
adapter()  : AdapterInterface|TaskAdapterInterface
Get adapter (alias)
addJob()  : Queue
Add job
addJobs()  : Queue
Add jobs
addTask()  : Queue
Add task (alias)
addTasks()  : Queue
Add tasks
clear()  : Queue
Clear jobs from queue
clearFailed()  : Queue
Clear dead-letter jobs from queue
clearTasks()  : Queue
Clear tasks from queue
create()  : Queue
Create the queue object
evaluateTasksOnce()  : array<string|int, mixed>
Evaluate every given task exactly once against the current time and run the ones that are due, returning the ones that ran (successfully or not) keyed by job ID. Coarse (non-sub-minute) tasks are always considered; pass $onlySubMinute = true to skip them (used by run()'s per-second tick loop, where a coarse task's single evaluation already happened on the shared first pass and doesn't need repeating).
events()  : Manager|null
Get event manager (alias)
fake()  : Queue
Create a Memory-backed queue for testing - a fake, in the sense familiar from other PHP frameworks' testing conventions. Note Memory's own constructor takes $leaseSeconds before $priority (Memory predates this method and that argument order is documented, pre-existing behavior elsewhere in this codebase) - fake()'s own parameter order matches create()'s $priority-before-lease convention instead, and translates between the two internally, so a caller of fake() never needs to know Memory's own argument order.
getAdapter()  : AdapterInterface|TaskAdapterInterface
Get adapter
getEvents()  : Manager|null
Get event manager
getName()  : string
Get name
getPriority()  : string
Get queue priority
getScheduledTasks()  : array<string|int, mixed>
Fetch every currently scheduled task from the adapter, once. Returns an empty array if the adapter doesn't support tasks (TaskAdapterInterface) or has none scheduled - callers don't need to duplicate that guard.
hasEvents()  : bool
Has event manager
hasName()  : bool
Has name
isFifo()  : bool
Is FIFO
isFilo()  : bool
Is FILO
isLifo()  : bool
Is LIFO (alias to FILO)
isLilo()  : bool
Is LILO (alias to FIFO)
run()  : array<string|int, mixed>
Run schedule
setAdapter()  : AbstractQueue
Set adapter
setEvents()  : Queue
Set event manager
setName()  : AbstractQueue
Set name
setPriority()  : Queue
Set queue priority
work()  : AbstractJob|null
Work next job
runWithTimeout()  : mixed
Run a job, enforcing its soft timeout when ext-pcntl is available.
triggerEvent()  : void
Trigger a lifecycle event. Uses this Queue's own event manager if one is set via setEvents(); otherwise falls back to $application's event manager if one was passed in and has events registered; otherwise does nothing. Never throws on its own account - if the resolved manager's trigger() call throws (e.g. a listener's own code throws), that exception propagates to the caller exactly as any other uncaught exception would.

Constants

FIFO

Queue priority constants

public mixed FIFO = 'FIFO'

FILO

public mixed FILO = 'FILO'

Properties

$events

Event manager, for lifecycle observability hooks (queue.job.*, queue.task.*).

protected Manager|null $events = null

If not set, and an Application with its own event manager is passed into work()/run(), that Application's event manager is used instead - see triggerEvent(). If neither is available, event firing is a silent no-op.

Methods

addJobs()

Add jobs

public addJobs(array<string|int, mixed> $jobs[, int|null $maxAttempts = null ]) : Queue
Parameters
$jobs : array<string|int, mixed>
$maxAttempts : int|null = null
Return values
Queue

addTask()

Add task (alias)

public addTask(Task $task[, int|null $maxAttempts = null ][, int|null $gracePeriod = null ]) : Queue
Parameters
$task : Task
$maxAttempts : int|null = null
$gracePeriod : int|null = null
Tags
throws
Exception
Return values
Queue

addTasks()

Add tasks

public addTasks(array<string|int, mixed> $tasks[, int|null $maxAttempts = null ]) : Queue
Parameters
$tasks : array<string|int, mixed>
$maxAttempts : int|null = null
Tags
throws
Exception
Return values
Queue

clearFailed()

Clear dead-letter jobs from queue

public clearFailed() : Queue
Return values
Queue

clearTasks()

Clear tasks from queue

public clearTasks() : Queue
Return values
Queue

evaluateTasksOnce()

Evaluate every given task exactly once against the current time and run the ones that are due, returning the ones that ran (successfully or not) keyed by job ID. Coarse (non-sub-minute) tasks are always considered; pass $onlySubMinute = true to skip them (used by run()'s per-second tick loop, where a coarse task's single evaluation already happened on the shared first pass and doesn't need repeating).

public evaluateTasksOnce(array<string|int, mixed> $tasks, Application|null $application[, bool $onlySubMinute = false ]) : array<string|int, mixed>

Before running a due task, atomically claims it for the current due-window via the adapter (claimTaskRun()) - if another worker sharing the same adapter storage already claimed this task's window, this call skips it silently rather than running it a second time.

Parameters
$tasks : array<string|int, mixed>

taskId => Task

$application : Application|null
$onlySubMinute : bool = false
Return values
array<string|int, mixed> —

jobId => Task, for every task that ran this pass

fake()

Create a Memory-backed queue for testing - a fake, in the sense familiar from other PHP frameworks' testing conventions. Note Memory's own constructor takes $leaseSeconds before $priority (Memory predates this method and that argument order is documented, pre-existing behavior elsewhere in this codebase) - fake()'s own parameter order matches create()'s $priority-before-lease convention instead, and translates between the two internally, so a caller of fake() never needs to know Memory's own argument order.

public static fake([string $name = 'pop-queue' ][, string|null $priority = null ][, int $leaseSeconds = 60 ]) : Queue
Parameters
$name : string = 'pop-queue'
$priority : string|null = null
$leaseSeconds : int = 60
Return values
Queue

getName()

Get name

public getName() : string
Return values
string

getPriority()

Get queue priority

public getPriority() : string
Return values
string

getScheduledTasks()

Fetch every currently scheduled task from the adapter, once. Returns an empty array if the adapter doesn't support tasks (TaskAdapterInterface) or has none scheduled - callers don't need to duplicate that guard.

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

taskId => Task

hasEvents()

Has event manager

public hasEvents() : bool
Return values
bool

hasName()

Has name

public hasName() : bool
Return values
bool

isFifo()

Is FIFO

public isFifo() : bool
Return values
bool

isFilo()

Is FILO

public isFilo() : bool
Return values
bool

isLifo()

Is LIFO (alias to FILO)

public isLifo() : bool
Return values
bool

isLilo()

Is LILO (alias to FIFO)

public isLilo() : bool
Return values
bool

run()

Run schedule

public run([Application|null $application = null ]) : array<string|int, mixed>

Evaluates every scheduled task fairly: all tasks get one shared evaluation pass immediately, then - only if at least one sub-minute task exists - up to 59 more passes (one per second) considering only the sub-minute tasks. This ensures no single task's per-tick work blocks any other task's evaluation on the same tick.

Parameters
$application : Application|null = null
Tags
throws
Exception
Return values
array<string|int, mixed>

setPriority()

Set queue priority

public setPriority([string $priority = 'FIFO' ]) : Queue
Parameters
$priority : string = 'FIFO'
Return values
Queue

runWithTimeout()

Run a job, enforcing its soft timeout when ext-pcntl is available.

protected runWithTimeout(AbstractJob $job, Application|null $application) : mixed

Exec-type jobs are exempt from this pcntl-based alarm entirely - AbstractJob::runExec() wires the job's timeout directly into Symfony\Process's own setTimeout(), which is both more precise and (unlike a pcntl alarm racing against a raw exec() call) actually capable of killing the spawned child process on expiry. Layering a second, competing pcntl alarm on top for the same job risks interrupting Process's own internal wait()/kill logic mid-flight if the alarm fires first, defeating the reliable-child-termination guarantee this task exists to add.

Parameters
$job : AbstractJob
$application : Application|null

triggerEvent()

Trigger a lifecycle event. Uses this Queue's own event manager if one is set via setEvents(); otherwise falls back to $application's event manager if one was passed in and has events registered; otherwise does nothing. Never throws on its own account - if the resolved manager's trigger() call throws (e.g. a listener's own code throws), that exception propagates to the caller exactly as any other uncaught exception would.

protected triggerEvent(string $name, array<string|int, mixed> $params[, Application|null $application = null ]) : void
Parameters
$name : string
$params : array<string|int, mixed>
$application : Application|null = null 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results