Time to Live

We may define Time to Live for Messages. This way if Message will not be handled within specific amount of time, it will be automatically discarded. This is useful in scenarios like sending notifications, where given notification like One Time Password may actually have meaning only for 5 minutes.

Message Handler Time to Live

You may delay handling given asynchronous message by adding #[Delayed] attribute.

#[TimeToLive(new TimeSpan(seconds: 50))]
#[Asynchronous("notifications")]
#[EventHandler(endpointId: "welcomeEmail")]
public function sendWelcomeNotificationWhen(UserWasRegistered $event): void
{
   // handle welcome notification
}

Using Expression language

To dynamically calculate expected TTL, we can use expression language.

#[TimeToLive(expression: 'headers["expirationTime"]']
#[Asynchronous("notifications")]
#[EventHandler(endpointId: "welcomeEmail")]
public function sendWelcomeNotificationWhen(UserWasRegistered $event): void
{
   // handle welcome notification
}

payload variable in expression language will hold Command/Event object. headers variable will hold all related Mesage Headers.

We could also access any object from our Dependency Container, in order to calculate the delay and pass there our Command:

#[Delayed(expression: 'reference("delayService").calculate(payload)']
#[Asynchronous("notifications")]
#[EventHandler(endpointId: "welcomeEmail")]
public function sendWelcomeNotificationWhen(UserWasRegistered $event): void
{
   
}

Message Time to Live

We may send an Message and tell Ecotone to set Time to Live using timeToLive Message Header:

$commandBus->sendWithRouting(
    "sendOneTimePassword",
    "userId",
    metadata: ["timeToLive" => new TimeSpan(minutes: 5)]
);

Asynchronous Message Channel need to support this option to be used

Controlling Header Override Behavior

By default, the #[TimeToLive] attribute will override any existing timeToLive header that was set when sending the message. However, you can change this behavior using the shouldReplaceExistingHeader parameter.

Using Attribute as Default (Not Override)

When you want the attribute to act as a default value that can be overridden by message metadata:

#[TimeToLive(new TimeSpan(minutes: 5), shouldReplaceExistingHeader: false)]
#[Asynchronous("notifications")]
#[EventHandler(endpointId: "sendOTP")]
public function sendOneTimePassword(OTPRequested $event): void
{
   // handle OTP sending
}

With shouldReplaceExistingHeader: false:

• If the message already has a timeToLive header, the attribute will not override it

• If the message does not have a timeToLive header, the attribute value will be used

This is useful when you want:

• Handler-level defaults via attributes

• Per-message overrides via metadata (e.g., different TTL based on message priority or type)