Download the PHP package qcodr/restate-sdk-laravel without Composer

Restate SDK for Laravel

Laravel integration for the Restate PHP SDK — durable execution (workflows, virtual objects, sagas, durable timers, exactly-once side effects) wired into Laravel's container, routing, and Artisan.

Write Restate services as ordinary Laravel classes (with constructor DI), list them in config, and serve them either from inside your app (a request/response route) or over true bidirectional HTTP/2 (php artisan restate:serve).

Why

Restate adds guarantees Laravel's native tools don't give you for multi-step, long-running, or per-entity-stateful work:

Requirements

• PHP 8.2+
• Laravel 12 or 13
• qcodr/restate-sdk-php (pulled in automatically)
• amphp/http-server only if you use php artisan restate:serve (bidi)

Installation

The service provider is auto-discovered.

Quick start

Define a service as a normal Laravel class — constructor dependencies are injected from the container:

Register it in config/restate.php:

Point a running Restate runtime at your app and invoke through the ingress:

One rule for handlers: they must be deterministic and stateless. Keep every DB / HTTP / mail / random call inside ctx->run() (a durable side effect); per-invocation data lives in local variables or Restate state, never in instance properties.

Serving

In-app route (default). The provider mounts a catch-all route at the configured prefix (restate by default), served request/response by your normal Laravel stack (FPM, Octane). Register the deployment at <app-url>/restate. Zero extra infrastructure.

Bidirectional streaming. For cancellation, signals, and fewer re-invokes on suspension-heavy handlers, run the amphp host instead:

Set config path to null to disable the in-app route when serving this way.

Calling Restate from Laravel

The two sections above expose your handlers to the runtime. The reverse direction — starting a Restate invocation from ordinary Laravel code (a controller, job, or listener) — goes through the Restate ingress with the RestateClient:

Configure the ingress in config/restate.php (ingress.url, RESTATE_INGRESS_URL; optional ingress.token, RESTATE_INGRESS_TOKEN → Authorization: Bearer). Full recipe — controllers, jobs, listeners, idempotency, delayed send, error handling — in docs/usecases/dispatch.md.

Configuration

config/restate.php:

Artisan

Use cases

Worked, tested examples live under tests/Examples/ (proven offline against the SDK — discovery, business logic, and the durable flow over a fake context) with copy-pasteable recipes:

• Saga — an order-processing workflow (reserve inventory → charge → ship) with automatic compensation on failure: a thin #[Workflow] over injected, idempotent services. The proof drives a failing payment and asserts inventory is released, shipping never runs, and a TerminalException surfaces.
• Rate limiter — a per-key token bucket as a #[VirtualObject]: single-writer state per key, no lockForUpdate / Redis race. The proof drains one key while another stays full, showing per-key isolation.
• Dispatch from Laravel — the caller side: start invocations (call-and-await, fire-and-forget send, keyed objects/workflows, idempotency, durable delayed send) from a controller, job, or listener via the RestateClient over the Restate ingress.
• Queue connection — dispatch existing ShouldQueue jobs on the restate connection (->onConnection('restate')) to run them durably on Restate (exactly-once, durable retries) with no queue:work worker.
• Validation — validate a handler's decoded-array input with Laravel's Validator at the boundary via the ValidatesInput trait, throwing a terminal 400 on bad input (the idiomatic answer to the array gotcha below).
• Testing — Restate::fake() + Restate::assertCalled(...) / assertSent(...), the Bus::fake() equivalent for Restate dispatches.
• Generators & discovery — php artisan make:restate-service (-object, -workflow) plus directory auto-discovery (config discover).
• Typed clients — php artisan restate:codegen generates an IDE-autocompletable client per service (GreeterClient::fromContext($ctx)->greet(...)).
• Scheduler — Schedule::restate('Svc','handler', $payload) ->dailyAt('03:00') fires durable Restate invocations from Laravel's scheduler.
• Observability — handler logs flow into Laravel's logging stack (replay-aware), and an optional Telescope watcher tags ingress dispatches.
• Auth & tenant — re-establish the authenticated user / tenant inside a handler from the headers the runtime forwards (withAuth), and forward them on outbound dispatches.

Several surface a real SDK boundary: JsonSerde hands handlers the decoded array, not a hydrated object, so a handler's input parameter is array/scalar and the value object is built (and validated — see the Validation trait) inside the handler.

Code quality

Mirrors the SDK's strict gate, all offline:

License

Apache-2.0