Laravel Temporal Laravel Package

Technical Evaluation

Architecture fit

• keepsuit/laravel-temporal is a Laravel service-provider wrapper around the official temporal/sdk-php. It gives Laravel-native config (config/temporal.php), workflow/activity registration, artisan generators, and testing helpers on top of Temporal's durable-execution runtime.
• Strong fit for long-running, multi-step, retry-heavy orchestration where state must survive process death: order fulfillment, billing/dunning with external payment retries, document/ETL pipelines, provisioning sagas. Poor fit for sub-second request-path work or anything already adequately served by Horizon/queues.
• The architectural boundary is the important part: workflows must be deterministic and side-effect-free, with all I/O pushed into activities. Laravel idioms (Eloquent, facades, now(), rand(), HTTP calls) are unsafe inside workflow code, so this package adds a second programming model to the codebase, not just a dependency.

Integration feasibility

• Composer install plus config publish is trivial. The real cost is infrastructure: a Temporal cluster (Cloud namespace or self-hosted with Cassandra/Postgres) and a RoadRunner worker binary (rr) as a second runtime alongside PHP-FPM. Deployment, CI images, and .rr.yaml config all become new owned artifacts.
• The 2.3.2 patch is a boot-time crash fix when spatie/laravel-data is absent (PR #79). It is a pure patch — no breaking changes, no deprecations, no new features. Its relevance is that it confirms spatie/laravel-data is an optional dependency and that the package previously had a failure path for teams not using it. That removes a concrete adoption blocker for our stack if we don't standardize on Data objects.

Technical risk

• Determinism violations are the highest-severity risk: a non-deterministic workflow only fails on replay, often in production, and requires workflow versioning/patching discipline to fix safely.
• Payload contract drift: the data converter (plain arrays or spatie Data DTOs) defines the serialization contract between workflow and activity. Changing a DTO shape can break in-flight executions that replay against old history. Treat payload classes as versioned public API.
• Dual-runtime operations: RoadRunner must be built, shipped, and kept in sync with the PHP code; a mismatch silently prevents workers from picking up task queues.
• Bus factor: single-maintainer package layered on an SDK that has itself churned. Budget for the possibility of forking or contributing fixes upstream. The 2.3.2 turnaround is a positive responsiveness signal.
• Scale ceiling: Temporal's default blob size limit (~2MB) and workflow history limits force claim-check patterns (S3/DB references) for large payloads.

Key questions

1. What is the supported matrix for Laravel 11/12 and PHP 8.3/8.4, and how closely does it track temporal/sdk-php releases?
2. Without spatie/laravel-data, what is the serialization story — plain arrays only, or a pluggable custom converter? (2.3.2 implies at least "doesn't crash," not necessarily "fully featured.")
3. Does the package expose Temporal's workflow versioning/patching primitives, or must we drop to the SDK?
4. What does TemporalFake cover — full workflow replay, or only activity mocking? Test fidelity determines how much confidence we get pre-prod.
5. Observability: OpenTelemetry integration, structured logging correlation, and Temporal Web UI access for on-call?
6. Multi-tenancy: do we need per-tenant namespaces, and does the config support multiple connections cleanly?

Integration Approach

Stack fit

• Assumes Laravel 10/11+, PHP 8.1+, Composer, and a container platform that can run a long-lived RoadRunner process. Fits naturally if we already run Horizon workers as separate deployments; conflicts if the platform only permits stateless HTTP containers.
• Coexists with the existing queue stack rather than replacing it: keep Horizon for fire-and-forget jobs, use Temporal only where durability, retries, and cross-service state machines are the actual requirement.

Migration path

• Do not migrate existing jobs. Pick one bounded, high-value workflow with real failure modes (e.g., multi-step payment retries or partner provisioning) and run it in parallel with the current implementation behind a feature flag.
• Keep Eloquent at the activity boundary: pass IDs and DTOs, never models, into workflow inputs. This keeps the workflow history small and the contract explicit.
• Adopt spatie/laravel-data deliberately, not incidentally. If we adopt it, version the DTOs in a dedicated namespace and treat renames as breaking changes.

Compatibility

• Pin the package and temporal/sdk-php to exact versions with a documented upgrade cadence; SDK upgrades are the likeliest source of breakage.
• Verify the optional-dependency fix in our own smoke test: install in a project without spatie/laravel-data, boot the app, register a workflow, and confirm no crash — this is the specific regression 2.3.2 addresses.

Sequencing

1. Provision Temporal (Cloud namespace first, self-host later if needed), TLS certs, secrets.
2. Build and publish the RoadRunner worker image; wire CI and health checks.
3. Publish config, smoke-test connectivity from a staging app.
4. Ship one workflow + its activities with explicit idempotency keys, retry policies, and timeouts.
5. Add TemporalFake-based tests and a replay/non-determinism check in CI.
6. Add dashboards and runbooks, then expand to a second workflow.

Operational Impact

Maintenance

• Two runtimes to patch (PHP app and RoadRunner), plus Temporal server/SDK upgrades and namespace/TLS rotation. Estimate a recurring engineering tax, not a one-off integration cost.
• Single-maintainer package: plan to track upstream issues, and pre-agree a policy for pinning vs. forking if a critical fix stalls.

Support

• On-call needs Temporal-specific runbooks that Laravel teams typically lack: stuck/blocked workflows, activity timeout storms, task-queue backlog, worker crash loops, non-determinism errors on replay.
• Temporal Web UI becomes a first-class debugging surface. Logs alone will not explain a workflow that is "running" but not progressing.

Scaling

• Workers scale horizontally per task queue; use separate worker pools per queue or namespace to isolate noisy workflows.
• Enforce payload limits with claim-check (store blobs in S3/DB, pass references) before volume grows. Watch workflow history size for long loops — prefer continue-as-new.

Failure modes

• Non-determinism on replay: highest severity, only surfaces during worker restart or upgrade. Mitigate with a design-review checklist and replay tests in CI.
• Boot-time failure from an absent optional dependency — precisely the class of bug fixed in 2.3.2. Worth noting that this bug shipped in a minor line and implies the boot path couples to optional packages; add a "minimal dependency" job to our test matrix.
• Payload/schema drift breaking in-flight executions (irrecoverable without careful versioning).
• RoadRunner misconfiguration or version skew causing silent worker non-registration; no jobs fail, work simply never starts.

Ramp-up

• 2–4 weeks for a Laravel-fluent engineer to reach productive autonomy. The Laravel surface is familiar; the conceptual load is durable execution — determinism, replay, idempotency, timeouts, versioning.
• Pair the first workflow with someone who has Temporal experience, or budget for a spike, plus a short internal design-review checklist. The 2.3.2 release does not change this picture; it modestly de-risks the "we don't use spatie/laravel-data" adoption path and demonstrates responsive maintenance.