Nexus API Reference

Envelope
in package

Read onlyYes
FinalYes

Immutable message wrapper that carries a user message through the mailbox system.

Every message sent via ActorRef::tell() is wrapped in an Envelope before it enters a mailbox. The envelope adds routing context — sender path, target path — and distributed-tracing identifiers (requestId, correlationId, causationId) so that message flows can be tracked across actor boundaries and serialized for remote transport.

Most user code never constructs envelopes directly; the actor runtime creates them internally. The Envelope is exposed in serialization adapters and the worker-pool transport layer where low-level routing is needed.

Example (worker-pool transport usage):

$envelope = Envelope::of($message, $senderPath, $targetPath)
    ->withSenderRef($replyRef)
    ->withMetadata(['x-trace-id' => $traceId]);
$transport->send($targetWorkerId, $envelope);
Tags
see
ActorRef::tell()

for the user-facing send API that creates envelopes

ActorPath

for the routing addresses carried by the envelope

EnvelopeSerializer

for serializing envelopes across process boundaries

psalm-api
psalm-immutable

Table of Contents

Properties

$causationId  : string
$correlationId  : string
$message  : object
$metadata  : array<string|int, mixed>
$requestId  : string
$sender  : ActorPath
$senderRef  : ActorRef|null
$target  : ActorPath

Methods

__construct()  : mixed
of()  : self
Creates an Envelope with empty metadata.
withCausationId()  : self
Return a new Envelope with an updated causation ID.
withCorrelationId()  : self
Return a new Envelope with an updated correlation ID.
withMetadata()  : self
Returns a new Envelope with updated metadata.
withRequestId()  : self
Return a new Envelope with an updated request ID.
withSender()  : self
Returns a new Envelope with updated sender.
withSenderRef()  : self
Returns a new Envelope with the given senderRef.

Properties

$correlationId

public string $correlationId

$metadata

public array<string|int, mixed> $metadata = []

Methods

__construct()

public __construct(object $message, ActorPath $sender, ActorPath $target, string $requestId, string $correlationId, string $causationId[, ActorRef|null $senderRef = null ][, array<string, string> $metadata = [] ]) : mixed
Parameters
$message : object
$sender : ActorPath
$target : ActorPath
$requestId : string
$correlationId : string
$causationId : string
$senderRef : ActorRef|null = null
$metadata : array<string, string> = []

withCausationId()

Return a new Envelope with an updated causation ID.

public withCausationId(string $causationId) : self

The causation ID identifies the direct parent message that triggered this one, enabling a causal DAG of message flows for distributed tracing.

Parameters
$causationId : string
Return values
self

withCorrelationId()

Return a new Envelope with an updated correlation ID.

public withCorrelationId(string $correlationId) : self

The correlation ID ties together all messages that belong to the same logical request chain (e.g. the original request and all downstream fan-out messages).

Parameters
$correlationId : string
Return values
self

withMetadata()

Returns a new Envelope with updated metadata.

public withMetadata(array<string, string> $metadata) : self
Parameters
$metadata : array<string, string>
Return values
self

withRequestId()

Return a new Envelope with an updated request ID.

public withRequestId(string $requestId) : self

The request ID uniquely identifies a single message send. Overriding it is useful in serialization adapters that reconstruct envelopes from a wire format.

Parameters
$requestId : string
Return values
self

withSender()

Returns a new Envelope with updated sender.

public withSender(ActorPath $sender) : self
Parameters
$sender : ActorPath
Return values
self

withSenderRef()

Returns a new Envelope with the given senderRef.

public withSenderRef(ActorRef $senderRef) : self
Parameters
$senderRef : ActorRef
Return values
self
On this page

Search results