Download the PHP package not-empty/omniq without Composer

OmniQ (PHP)

PHP SDK for OmniQ, the Redis + Lua queue with deterministic behavior across languages.

This SDK follows the OmniQ core contract and uses the same Lua scripts as the reference implementations.

Status

Current implementation covers:

• publish / publishJson
• reserve
• heartbeat
• ackSuccess / ackFail
• promoteDelayed / reapExpired
• pause / resume / isPaused
• retryFailed / retryFailedBatch
• removeJob / removeJobsBatch
• childsInit / childAck
• consume

The consumer path has smoke coverage for:

• success flow
• failure flow
• heartbeat on long-running jobs
• lost lease handling
• graceful drain on SIGTERM
• fast exit on SIGINT with drain=false
• pause / resume
• grouped jobs and group limits
• child workflow primitives

Requirements

• PHP 8.3+
• ext-redis
• ext-pcntl
• Redis or Valkey with Lua enabled

This SDK uses phpredis as the transport. When using host/port, the transport attempts RedisCluster first and falls back to plain Redis when the target is not cluster-enabled, mirroring the Python SDK behavior.

Installation

Development Environment

This repository includes a local Docker setup:

Services:

• omniq-redis
• omniq-valkey
• omniq-php

Quick Start

Publish

Publish Structured Payload

Consume

Consumer Notes

• The consumer is designed for CLI workers
• Heartbeat support requires ext-pcntl
• In the basic CLI pcntl runtime, the consumer uses 2 persistent Redis connections per worker
• One connection is used by the main consumer loop and one by the heartbeat helper process
• This is a PHP runtime tradeoff for safe heartbeat behavior in the plain CLI worker model
• drain=true finishes the current job and exits cleanly on stop signals
• drain=false exits immediately on SIGINT

Handler Context

Inside handler(JobCtx $ctx):

• $ctx->queue
• $ctx->jobId
• $ctx->payloadRaw
• $ctx->payload
• $ctx->attempt
• $ctx->maxAttempts
• $ctx->lockUntilMs
• $ctx->leaseToken
• $ctx->gid
• $ctx->exec

Example:

Queue Discovery

Use scanQueues() for queue discovery. It scans Redis for *:stats keys and is intended for admin/bootstrap flows rather than hot-path UI polling.

Queue names are validated in the SDK and may contain only letters, numbers, ., _, and -.

Administrative Operations

Retry Failed

Retry Failed Batch

Remove Job

Remove Jobs Batch

Pause / Resume / IsPaused

Pause is flag-only and blocks only new reserves.

Grouped Jobs

Behavior:

• FIFO inside the same group
• group concurrency limited by groupLimit
• other groups can still make progress in parallel

Child Workflows

The execution helper available on JobCtx exposes:

• $ctx->exec->publish(...)
• $ctx->exec->pause(...)
• $ctx->exec->resume(...)
• $ctx->exec->isPaused(...)
• $ctx->exec->childsInit(...)
• $ctx->exec->childAck(...)

Parent Example

Child Example

Properties:

• idempotent decrement per child id
• safe under retries
• counter is deleted when it reaches zero

Examples

The examples/ directory mirrors the Python example matrix and is intended for both documentation and manual testing:

• examples/simple/
• examples/max_attempts/
• examples/pause_resume/
• examples/childs/

Notes

• Payloads must be structured JSON
• The Lua scripts are vendored in src/core/scripts
• The PHP SDK is intentionally thin over Redis + Lua semantics
• The current worker runtime target is CLI PHP, not FrankenPHP yet
• Contract regression coverage lives in omniq-core/validation