Download the PHP package ruudk/absurd-php-sdk without Composer

Absurd SDK for PHP

PHP SDK for Absurd: a PostgreSQL-based durable task execution system.

Absurd is the simplest durable execution workflow system you can think of. It's entirely based on Postgres and nothing else. It's almost as easy to use as a queue, but it handles scheduling and retries, and it does all of that without needing any other services to run in addition to Postgres.

Note: This PHP SDK is still in its early stages. Absurd itself has been running in production at Earendil since its initial release.

What is Durable Execution?

Durable execution (or durable workflows) is a way to run long-lived, reliable functions that can survive crashes, restarts, and network failures without losing state or duplicating work. Instead of running your logic in memory, a durable execution system decomposes a task into smaller pieces (step functions) and records every step and decision.

How It Works

This SDK uses PHP Fibers to provide a clean, synchronous-looking API for durable workflows. When you call methods like $ctx->step(), $ctx->awaitEvent(), or $ctx->sleepFor(), the Fiber suspends execution, allowing the SDK to checkpoint progress to the database. When the task resumes (after a crash, timeout, or event), execution continues from exactly where it left off.

This means you can write workflow code that looks like normal sequential PHP code, while the SDK handles all the complexity of persistence, retries, and resumption behind the scenes.

Installation

Quick Start

Client Configuration

The Absurd constructor accepts a Connection instance instead of a raw PDO object. Wrap your PDO with PdoConnection (or implement your own adapter, e.g. for Doctrine DBAL):

The serializer defaults to JsonSerializer (no extra dependencies). Pass SymfonySerializer if you need typed object deserialization:

Custom Database Connection

Implement Connection\Connection to integrate with any database layer (e.g. Doctrine DBAL):

Queue Management

Task Registration

Spawning Tasks

Retry Strategies

Task Context Methods

Inside a task handler, you have access to TaskContext with these methods:

Emitting Events

Cancelling Tasks

Running tasks will stop at their next checkpoint, heartbeat, or await event call.

Retrying Tasks

Force a retry of a failed or cancelled task:

Use the BeforeRetryEvent to modify retry options from a listener (same pattern as BeforeSpawnEvent).

Retrieving Task Info

Worker Configuration

Worker Concurrency Model

PHP workers process tasks sequentially within a single process. The batchSize option controls how many tasks are claimed from the database in each poll, but they are still executed one at a time. This design ensures:

• Predictable resource usage per worker
• Simple error isolation (one task failure doesn't affect others)
• No need for complex thread-safety considerations

For concurrent task processing, run multiple worker processes:

Or use a process manager like Supervisor:

Events

Use a PSR-14 EventDispatcherInterface for lifecycle hooks and error handling.

Available Events

Typed Payloads

With a serializer that supports type hydration (like the shipped SymfonySerializer), you can use typed objects as task parameters:

Idempotency Keys

Use idempotency keys to prevent duplicate task creation:

Use task ID for deriving idempotency keys for external APIs:

Local Development

Prerequisites

• Docker and Docker Compose
• GitHub CLI (gh) - for downloading Absurd binaries

Quick Start

After running make up:

• PostgreSQL is available at localhost:54329
• Habitat UI (task dashboard) is available at http://localhost:7890

Running the Examples

The SDK includes two comprehensive examples:

E-commerce Order Fulfillment

Demonstrates checkpoints, events, sub-tasks, and trace propagation in a realistic order processing scenario.

AI Agent with Tool Calling

Demonstrates a durable AI agent workflow based on this blog post. The agent loops through conversation steps, calling tools as needed, with each iteration durably checkpointed.

Features:

• Loop-based agent with automatic checkpointing per iteration
• OpenAI integration with tool calling (get_weather, search_web, calculate)
• Automatic recovery from crashes - resumes from last checkpoint
• Durable conversation state stored in PostgreSQL

Make Commands

Production Setup

For production, initialize Absurd in your PostgreSQL database:

API Reference

Absurd Class

TaskContext Class

SpawnResult Class