Download the PHP package dealnews/inngest-php-sdk without Composer

Inngest PHP SDK

Unofficial PHP SDK for Inngest - Build event-driven workflows with durable execution.

Installation

Requirements

• PHP 8.1 or higher
• ext-json
• ext-hash

Features

• ✅ Event-driven workflows - Trigger functions from events
• ✅ Durable execution - Automatic retries and step memoization
• ✅ Step functions - Break work into retriable blocks
• ✅ Sleep & delays - Pause execution for minutes, hours, or days
• ✅ Wait for events - Coordinate across async workflows
• ✅ Function invocation - Call other Inngest functions
• ✅ Cron triggers - Schedule recurring tasks
• ✅ Concurrency control - Limit parallel execution
• ✅ Priority queues - Dynamic execution ordering
• ✅ Debounce - Delay execution until events settle
• ✅ Rate limiting - Hard limit on function runs per time period
• ✅ Throttling - FIFO queueing with burst support
• ✅ Singleton - Ensure only one run executes at a time
• ✅ Send events from steps - Emit events as retriable steps
• ✅ HTTP fetch steps - Make durable HTTP requests as retriable steps
• ✅ Checkpointing - Execute multiple steps per invocation for efficiency
• ✅ Middleware - Hook into function execution lifecycle
• ✅ Dev mode - Local development with Inngest dev server
• ✅ Type safety - Full PHP 8.1+ type declarations

Quick Start

1. Create an Inngest Client

2. Define a Function

3. Serve Functions

4. Send Events

Using Steps

Steps enable you to break your function into retriable blocks:

Wait for Events

Invoke Other Functions

Send Events from a Step

HTTP Fetch as a Step

Configuration

The SDK uses environment variables for configuration:

Or configure programmatically:

Error Handling

Non-Retriable Errors

Retry After Specific Time

Cron Triggers

Concurrency Control

Limit how many steps can run simultaneously across all function runs. Useful for rate-limiting external APIs, managing resources, or preventing overwhelming downstream services.

Basic Limit

Per-User Limits

Multi-Level Limits

Concurrency Options

• limit: Maximum concurrent steps (0 = unlimited)
• key: Expression to group concurrency (e.g., event.data.user_id, event.data.region)
• scope: Where the limit applies
  • fn (default): Per function
  • env: Per environment (production, staging, etc.)
  • account: Across entire account

Heads-up: Maximum of 2 concurrency configurations per function.

See examples/concurrency.php for more examples.

Priority

Dynamically prioritize function runs based on event data. Higher priority runs execute ahead of lower priority ones within the same function queue.

Basic Priority

Conditional Priority

Delayed Priority

Priority Options

• run: CEL expression that returns an integer priority factor
  • Range: -600 to 600 seconds (enforced by Inngest)
  • Positive values: Run ahead of jobs enqueued up to N seconds ago
  • Negative values: Delay execution by N seconds
  • 0: No priority (default queue position)

How it works: When a function run is enqueued, Inngest evaluates the expression using the event data. The result adjusts the run's position in the queue relative to other pending runs.

Heads-up:

• Most useful when combined with concurrency limits (jobs wait in queue)
• Invalid expressions evaluate to 0 (no priority)
• Out-of-range values are automatically clipped by Inngest

See Inngest Priority Documentation for more details.

Debounce

Delay function execution until events stop arriving for a specified period. Prevents wasted work when functions might be triggered rapidly in succession (user input, webhook floods, frequent updates).

The function runs once using the last event received as input data.

Basic Debounce

Per-Key Debounce

With Timeout

Complex Key Expression

Debounce Options

• period (required): Time to wait after last event
  • Format: <number><unit> where unit is s, m, h, or d
  • Range: 1s to 7d (168 hours)
  • Examples: 30s, 5m, 2h, 7d
• key (optional): CEL expression to group debounce windows
  • Each unique key value gets its own debounce period
  • Examples: event.data.user_id, event.data.region
• timeout (optional): Maximum wait time before forcing execution
  • Same format and range as period
  • Ensures function eventually runs even if events keep arriving

How it works:

1. First event starts the debounce period
2. Each new matching event resets the period timer
3. Function runs when period expires with no new events
4. If timeout is set, function runs after timeout regardless of new events

Use cases:

• User input: Wait for user to stop typing before processing
• Webhook processing: Batch rapid webhook updates into single run
• Data synchronization: Use latest data after updates settle
• Rate limiting: Prevent overwhelming downstream services

Heads-up:

• Cannot combine debounce with batching
• Function receives only the last event, not all events
• Use rate limiting if you need the first event instead of last

See Inngest Debounce Documentation for details.

Singleton

Ensure only a single run of a function (or per unique key) is executing at a time. Prevents duplicate work, race conditions, and ensures sequential processing of events.

Basic Singleton - Skip Mode

Per-User Singleton

Cancel Mode

Complex Key Expression

Singleton Options

• mode (required): Behavior when new run arrives
  • "skip": Skip new runs if another is already executing
  • "cancel": Cancel existing run and start the new one
• key (optional): CEL expression to group singleton behavior
  • Each unique key value gets its own singleton rule
  • Examples: event.data.user_id, event.data.tenant_id

How It Works

Skip Mode:

1. First event starts the function run
2. While running, new matching events are skipped/discarded
3. Function completes with first event's data
4. Next event can then start a new run

Cancel Mode:

1. First event starts the function run
2. New matching event cancels the in-progress run
3. New run starts immediately with latest event
4. Rapid events may cause some to be skipped (debounce-like)

When to Use Each Mode

Use Skip Mode when:

• Preventing duplicate work (only need to process once)
• Protecting expensive operations (AI, heavy compute)
• Sequential processing required (database migrations)
• Resource limits (third-party API rate limits)

Use Cancel Mode when:

• Latest data matters most (user profile updates)
• Older data becomes stale (real-time dashboards)
• Want to process most recent event (search queries)

Use Cases

• Data synchronization: Third-party API syncs (skip mode)
• AI processing: Expensive computations (skip mode)
• Profile updates: Always use latest data (cancel mode)
• Report generation: One report at a time per customer (skip + key)
• Database migrations: Sequential execution required (skip mode)

Compatibility

Works with:

• ✅ Debounce
• ✅ Priority
• ✅ Rate limiting
• ✅ Throttling

Does not work with:

• ❌ Batching (singleton incompatible)
• ⚠️ Concurrency (singleton implies concurrency=1)

Heads-up:

• Failed functions still skip new runs during retry
• Cancel mode with rapid events may skip some (not all are cancelled)
• Singleton ensures "at most one" run, not "exactly one"

See Inngest Singleton Documentation for details.

Rate Limiting

Set a hard limit on how many function runs can start within a time period. Events exceeding the limit are skipped (not queued). Uses the Generic Cell Rate Algorithm (GCRA) for smooth distribution.

Basic Rate Limit

Per-User Rate Limiting

Per-Customer and Region

Rate Limit Options

• limit (required): Maximum runs per period
  • Must be >= 1
• period (required): Time window
  • Format: <number><unit> where unit is s, m, or h
  • Range: 1s to 24h (does NOT support days)
  • Examples: 30s, 10m, 2h, 24h
• key (optional): CEL expression to group rate limits
  • Each unique key value has its own independent limit
  • Examples: event.data.user_id, event.data.api_key

How It Works

1. Uses Generic Cell Rate Algorithm (GCRA) for smooth distribution
2. Events exceeding limit are skipped/discarded (lossy behavior)
3. Period begins when first matching event is received
4. Each unique key value has its own rate limit tracker

Use Cases

• External API limits: Enforce third-party API rate limits
• Resource protection: Prevent overwhelming downstream services
• Cost control: Limit expensive operations (AI, compute)
• Abuse prevention: Per-user/API key rate limiting

Compatibility

Works with:

• ✅ Concurrency, priority, debounce, singleton, throttling

Does not work with:

• ❌ Batching (not yet implemented)

Heads-up:

• Events exceeding limit are permanently lost (use throttling for lossless queueing)
• Rate limit is enforced server-side by Inngest
• Maximum period is 24 hours (for longer periods, use throttling with up to 7 days)

See Inngest Rate Limiting Documentation for details.

Throttling

Limit how many function runs can start within a time period, with excess runs enqueued for future execution (FIFO). Unlike rate limiting which skips events, throttling ensures no data loss.

Basic Throttle

With Burst Support

Per-User Throttling

Complex Key Expression

Throttle Options

• limit (required): Base number of runs per period
  • Must be >= 1
• period (required): Time window
  • Format: <number><unit> where unit is s, m, h, or d
  • Range: 1s to 7d (supports days unlike rate limiting)
  • Examples: 30s, 10m, 2h, 7d
• burst (optional): Extra runs allowed during spikes
  • Must be >= 0 (default: 0, no bursting)
  • Total capacity: limit + burst
  • Example: limit=10, burst=5 allows 15 runs per period
• key (optional): CEL expression to group throttles
  • Each unique key value has its own throttle
  • Examples: event.data.user_id, event.data.tenant_id

How It Works

1. Uses Generic Cell Rate Algorithm (GCRA)
2. Breaks period into windows based on limit
3. Events exceeding limit are enqueued (FIFO) for future execution
4. Burst parameter allows temporary spikes
5. Each unique key value has its own throttle tracker

FIFO Behavior

When the limit is reached:

1. Excess events are added to a queue (First In, First Out)
2. As capacity becomes available, queued events execute in order
3. No events are lost (unlike rate limiting)

Burst Parameter

The burst parameter handles traffic spikes:

• Without burst (burst=0): Admits exactly limit runs per period
• With burst (burst>0): Admits up to limit + burst runs per period
• Example: limit: 100, burst: 10 allows 110 runs per hour during spikes
• Useful for: API burst allowances, handling temporary traffic increases

Use Cases

• API rate limit compliance: Match external API limits with burst allowance
• Smooth traffic spikes: Evenly distribute execution over time
• Background job processing: Control processing rate without data loss
• Resource management: Prevent overwhelming services while queuing excess
• Cost control: Limit expensive operations but process all eventually

Throttle vs Rate Limit

Compatibility

Works with:

• ✅ Concurrency, priority, debounce, singleton, rate limiting

Does not work with:

• ❌ Batching (not yet implemented)

Heads-up:

• All events are eventually processed (FIFO queue)
• Burst capacity refreshes each period
• Throttle is enforced server-side by Inngest
• Supports longer periods (7 days) vs rate limiting (24 hours max)

See Inngest Throttling Documentation for details.

Checkpointing

Checkpointing allows the SDK to execute multiple steps within a single HTTP invocation by persisting step results to Inngest in the background. This reduces round-trip overhead for functions with many fast steps.

Three static presets are available:

Or configure manually:

Middleware

Middleware hooks into the function execution lifecycle for logging, monitoring, input/output transformation, and event interception.

Available lifecycle hooks (all optional):

Development

The SDK follows PSR standards and uses:

• snake_case for variables and properties
• camelCase for method names
• Protected visibility by default

Testing

Resources

• Inngest Documentation
• SDK Specification
• Support