Download the PHP package dskripchenko/laravel-delayed-process without Composer

Laravel Delayed Process

Language: 中文

Asynchronous execution of long-running operations in Laravel with UUID-based tracking, automatic retry, security allowlist, and transparent frontend interceptors for Axios, Fetch, and XHR.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Architecture
• Process Lifecycle
• Project Structure
• Backend API
• Frontend Interceptors
• Configuration Reference
• Database Schema
• Security
• Cookbook
• License

Features

• Async Processing — offload heavy operations to a queue, return UUID immediately
• UUID Tracking — every process gets a UUIDv7 for status polling
• Automatic Retry — configurable max attempts with error capture on final failure
• Security Allowlist — only explicitly allowed entity classes can be executed
• Frontend Interceptors — transparent Axios, Fetch, and XHR interceptors that auto-poll until completion
• Batch Polling — BatchPoller class for polling multiple UUIDs in a single request
• Loop Prevention — X-Delayed-Process-Poll header prevents interceptors from re-intercepting poll requests
• Lifecycle Events — ProcessCreated, ProcessStarted, ProcessCompleted, ProcessFailed events for observability
• Progress Tracking — 0-100% progress updates via ProcessProgressInterface
• Webhook Callbacks — HTTP POST notifications to callback_url on terminal status
• TTL / Expiration — automatic process expiration via expires_at + delayed:expire command
• Cancellation — cancel processes in new/wait status via builder
• Per-entity Queue Config — configure queue, connection, and timeout per entity class
• Artisan Commands — delayed:process, delayed:clear, delayed:unstuck, delayed:expire, delayed:migrate-v1 (legacy migration)
• Structured Logging — captures all MessageLogged events during execution, configurable buffer limit
• Atomic Claiming — race-condition-safe process claiming via atomic UPDATE
• PostgreSQL Optimized — partial indexes, JSONB columns, TIMESTAMPTZ; MySQL/MariaDB also supported

Requirements

Installation

Publish the configuration file:

Run the migration:

Register allowed entities in config/delayed-process.php:

Quick Start

1. Create a Handler

2. Trigger a Delayed Process (Backend)

3. Status Endpoint

4. Frontend — Axios Interceptor

Architecture

Lifecycle Overview

Component Overview

Contracts

All bindings are registered in DelayedProcessServiceProvider. Override via Laravel's service container for custom implementations.

Events

Process Lifecycle

Status Transitions

Retry Logic

1. Worker atomically claims process: UPDATE ... SET status='wait', try=try+1 WHERE status='new'
2. Handler executes
3. On success: status → done, result saved to data
4. On failure:
   • If try < attempts: status → new (eligible for retry)
   • If try >= attempts: status → error, error details saved

Project Structure

Backend API

Creating Processes

Use ProcessFactoryInterface (resolved via DI):

What happens inside make():

1. Validates entity is in allowed_entities config
2. Validates class and method exist
3. Validates parameters are JSON-serializable
4. Creates DelayedProcess model in a DB transaction (auto-generates UUIDv7, sets status=new, expires_at from TTL config)
5. Configures job queue/connection/timeout from per-entity config
6. Dispatches DelayedProcessJob to the queue
7. Fires ProcessCreated event
8. Returns the persisted model

Creating with Webhook Callback

When the process reaches a terminal status (done, error, expired, cancelled), an HTTP POST is sent to the callbackUrl with {uuid, status, data}.

Per-entity Queue Configuration

Status Endpoint Response

DelayedProcessResource returns:

Notes:

• data is only included when status is terminal (done, error, expired, cancelled)
• error_message and is_error_truncated are only included when an error exists
• progress (0-100) reflects execution progress
• started_at and duration_ms track execution timing

Artisan Commands

delayed:process — Synchronous Worker

Processes delayed tasks without requiring a queue worker. Useful for development or single-server deployments.

delayed:clear — Cleanup Old Processes

Deletes terminal (done / error) processes older than a specified number of days.

delayed:unstuck — Reset Stuck Processes

Resets processes stuck in wait status back to new so they can be retried.

delayed:expire — Expire TTL Processes

Marks processes whose expires_at has passed as expired.

delayed:migrate-v1 — Legacy Migration

Upgrades the database schema from the legacy structure. Adds error_message / error_trace columns, converts columns to JSONB (PostgreSQL) or JSON (MySQL), creates partial/composite indexes, and adds CHECK constraint.

Frontend Interceptors

The resources/js/delayed-process/ module provides transparent interceptors that automatically detect delayed process responses and poll until completion.

How It Works

1. Your API returns a response containing { payload: { delayed: { uuid: "..." } } }
2. The interceptor detects the UUID
3. It starts polling the status endpoint: GET {statusUrl}?uuid={uuid}
4. When status becomes done, the interceptor replaces the response payload with the result data
5. When status becomes error, expired, or cancelled, the interceptor throws a DelayedProcessError
6. Polling requests include X-Delayed-Process-Poll: 1 header to prevent infinite loops

File Structure

Axios Interceptor

Fetch Patch

XHR Patch

DelayedProcessConfig

CSRF token from <meta name="csrf-token"> is automatically included in poll requests.

Batch Poller

For polling multiple processes at once (e.g., bulk operations):

DelayedProcessError

Thrown when a process completes with error, expired, or cancelled status, or polling times out.

Loop Prevention

All polling requests include the header X-Delayed-Process-Poll: 1. The interceptors check for this header and skip interception on poll requests, preventing infinite polling loops.

Configuration Reference

File: config/delayed-process.php

Database Schema

Table: delayed_processes

Indexes

PostgreSQL (partial indexes for optimal performance):

MySQL / MariaDB (composite indexes):

Constraints

• CHECK (status IN ('new', 'wait', 'done', 'error', 'expired', 'cancelled')) on all databases

Security

Entity Allowlist

Only classes listed in config('delayed-process.allowed_entities') can be executed. Attempting to create a process with an unlisted class throws EntityNotAllowedException.

Callable Validation

Before execution, CallableResolver verifies:

1. Entity class is in the allowlist
2. Class exists (class_exists())
3. Method exists (method_exists())

Instantiation uses app($entity) — full Laravel DI container support.

Log Privacy

Set log_sensitive_context to false (default) to strip context arrays from captured log entries. Only log level, timestamp, and message are stored.

CSRF Protection

The frontend poller automatically reads <meta name="csrf-token"> and includes it in poll request headers. Ensure your status endpoint is behind CSRF middleware or explicitly verify the token.

Cookbook

For recipes, patterns, and troubleshooting, see the Cookbook.

Available in: 中文

Frontend Integration Guide

For a detailed step-by-step guide on integrating interceptors into Vue.js 3 and React applications, see the Frontend Interceptors Guide.

Includes: composables/hooks, progress tracking, batch polling, error handling, SSR support, and testing.

License

MIT © Denis Skripchenko