Weave Code
Laravel Temporal Laravel Package
keepsuit/laravel-temporal
Laravel Temporal integrates the Temporal PHP SDK with Laravel, making it easy to define and register workflows and activities, configure task queues and workers, and run durable background workflows using familiar Laravel configuration and Artisan commands.
Laravel integration with temporal.io workflow engine
Frequently asked questions about Laravel Temporal
- What is keepsuit/laravel-temporal used for?
- It is a Laravel service-provider wrapper around the official temporal/sdk-php package. It lets Laravel applications define and register Temporal workflows and activities, configure task queues and workers, and run durable background workflows using Laravel configuration and Artisan commands. It fits long-running, multi-step, retry-heavy orchestration such as order fulfillment, billing retries, document pipelines, and provisioning sagas.
- How do I install and configure laravel-temporal?
- Install it with Composer and publish the package configuration to create config/temporal.php. You then configure your Temporal connection, task queues, and worker settings, and register workflows and activities through the package. You will also need a Temporal cluster or Temporal Cloud namespace plus a running worker process.
- Does laravel-temporal support Laravel 11, Laravel 12, PHP 8.3, and PHP 8.4?
- The package is assessed as targeting Laravel 10/11 and later with PHP 8.1 and later, so Laravel 11 is within the expected range. Exact support for Laravel 12 and PHP 8.3/8.4 should be confirmed against the package composer constraints and README before adoption. Also check how closely the package tracks temporal/sdk-php releases, since the SDK is the underlying runtime dependency.
- Do I need spatie/laravel-data to use laravel-temporal?
- No, spatie/laravel-data is an optional dependency rather than a hard requirement. Version 2.3.2 fixed a boot-time crash that occurred when spatie/laravel-data was absent, which confirms the package can run without it. Without Data objects, payloads are typically handled as plain arrays, but you should verify the current serialization and custom converter options for your use case.
- Can I use Eloquent, facades, HTTP calls, or now() inside Temporal workflows?
- No, Temporal workflows must be deterministic and side-effect-free, so Laravel idioms such as Eloquent, facades, now(), rand(), and direct HTTP calls are unsafe inside workflow code. All I/O and non-deterministic work should be pushed into activities. This means adopting laravel-temporal adds a second programming model to your codebase, not just another dependency.
- What is the difference between laravel-temporal and Laravel Horizon or queues?
- Horizon and Laravel queues are a good fit for fire-and-forget jobs and short request-path work. Temporal is designed for durable execution where multi-step state must survive process death, with strong retry semantics and cross-service state machines. The package can coexist with your existing queue stack: keep Horizon for simple jobs and use Temporal only where durability and orchestration are the actual requirement.
- How do I test Temporal workflows in Laravel, and what does TemporalFake cover?
- The package provides Laravel testing helpers, including TemporalFake, for testing workflows and activities without running a full Temporal cluster. You should verify whether TemporalFake supports full workflow replay or only activity mocking, because test fidelity determines how much confidence you get before production. Determinism and payload contract changes are best covered by replay-style tests where possible.
- How do I deploy and run laravel-temporal workers with RoadRunner?
- Temporal workers require a long-lived RoadRunner binary, usually rr, running alongside your PHP-FPM application. You will need to build and ship that worker image, maintain .rr.yaml configuration, and keep the RoadRunner binary in sync with your PHP code. A mismatch can silently prevent workers from picking up task queues, so deployment and CI artifacts should be treated as owned infrastructure.
- Does laravel-temporal expose Temporal workflow versioning and patching primitives?
- The package is primarily a Laravel integration layer, and the assessment notes that workflow versioning and patching may require dropping down to the underlying temporal/sdk-php. Determinism violations often surface only on replay, so versioning discipline is critical for safely changing in-flight workflows. Confirm the current API surface before relying on package-level versioning helpers.
- What production risks should I consider before adopting laravel-temporal?
- The highest-severity risk is non-deterministic workflow code, which may fail only during replay and often in production. Payload classes act as a serialization contract between workflows and activities, so treat DTO or array shapes as versioned public API and avoid breaking in-flight executions. Also plan for dual-runtime operations, Temporal payload and history limits, observability and on-call access, multi-tenancy needs, and the bus factor of a single-maintainer package layered on a churning SDK.
Weaver
How can I help you explore Laravel packages today?