is it always an Envelope? Or maybe itcould be an Envolope?

It's always anEnvelope if you implements the interface.

Note: that's true considering our bus implementation which will always inject the message wrapped in an Envelope. But we currently also useEnvelope::wrap in envelope aware middleware and most tests are callinghandle on envelope aware middleware with a message directly, not an envelope.
We could removeEnvelope::wrap and fix tests of these middleware, but IMHO it's still another hintsymfony/symfony#27322 is needed for clarity & better design.

Is this the main use-case for an envelop-aware middleware? Or would we more commonly be reading some configuration from the envelope?

Both are good use cases tbh

I think reading would be way more common and should be showcased instead. I would put a note about being extra cautious about altering the envelope or its message as it'll be completely transparent. Even if there are legit use-cases.

About altering/replacing the message, the tactician docs says:

You don’t have to pass the same command to $next that came in! If you’re working with a legacy system and want to convert or modify the incoming commands, you’re free to do so. Just think carefully!

Also showing an example where we read the envelope items would make the purpose of those items more understandable.

handlers will always get the message (and I think it should stay as is as the end of the pipe), never the Envelope, so I think mentioning handlers here is misleading.

I think reading would be way more common and should be showcased instead. I would put a note about being extra cautious about altering the envelope or its message as it'll be completely transparent. Even if there are legit use-cases.

About altering/replacing the message, the tactician docs says:

You don’t have to pass the same command to $next that came in! If you’re working with a legacy system and want to convert or modify the incoming commands, you’re free to do so. Just think carefully!

Also showing an example where we read the envelope items would make the purpose of those items more understandable.

- configuration+ marker item

?

Actually, theWrapIntoReceivedMessage is neither a middleware, neither it is used in Symfony core. That's theWorker that call thereceive method with a$handleradding theReceivedMessage marker to the envelope.

Hence I wondered multiple times if it was really intended? Should we remove theWrapIntoReceivedMessage decorator? Should we decorate in the core any created receiver? Should the worker only dispatch the received envelope to the bus, or keep addingReceivedMessage?

We could mention others built-in configurations available (justValidationConfiguration for now) here or in another section.

Just did 👍

Just did 👍

I think we should remove the last sentence. I think it's obvious that, if you do NOT implement ``EnvelopeAwareInterface`, that you receive the normal message. So, this sentence made me wonder if you were actually saying something different.

Is thisget() method something that lives onEnvelope? Isn't there always just one message inside an Envelope? If so, why do we pass an argument here? Or, could you also pass something like$message->get(SerializerConfiguration::class) to get those types of things out?

Also, suppose some similar code: if$message->get(MyMessage::class) is null, does it mean that this message is NOT originally aMyMessage isntance, right? I mean, it's equivalent to!$message instanceof MyMessage in a middleware withoutEnvelopAwareInterface?

Some inline comments with some of these answers might be all we need :)

Also, is it a real use-case to look need to know whether or not a message was just received? If you're using an async transport and you want to do something for a specific message type, is it important that you make sure this processing is done only when your message has been "received"? If so, why? And if so, how could I both perform my action only when the message is "received" AND only check the class of the original message (e.g. I need to do something when myMyMessage class is "received"? Or is that totally not the correct pattern.

if $message->get(MyMessage::class) is null, does it mean that this message is NOT originally a MyMessage isntance, right?

There is mis interpretation here. TheReceivedMessage class is not an example here, it's an actual envelope item within the component has is a marker that represents that the message has just been received. It's needed to have the router middleware ignoring them (otherwise we would have a receive -> send) loop.

Or, could you also pass something like $message->get(SerializerConfiguration::class) to get those types of things out?

That's notalso, that's the only thing you can do :)

how could I both perform my action only when the message is "received" AND only check the class of the original message

if (nul !==$message->get(ReceivedMessage::class) &&$message->getMessage()instanceof YourOwnMessageClass) {// Your logic...}

Might be clearer if werename$message to$envelope?

The title of this section and the introduction is not very clear to me. Here is a reword proposal:

Before:

Envelope--------The notion of an envelope is a concept that helps add context around themessages. An envelope is a message and a set of data. From a user's perspective, thisallows you to set some configuration around the message. For example, to set the serializationgroups used when the message goes through the transport layer, wrap your messagein an ``Envelope`` and add some ``SerializerConfiguration``::

After:

Adding Metadata to Messages (Envelopes)---------------------------------------If you need to add metadata or some configuration to a message, wrap it with the:class:`Symfony\\Component\\Messenger\\Envelope` class. For example, to set theserialization groups used when the message goes through the transport layer, usethe ``SerializerConfiguration`` envelope::

Much better 👍

Much better 👍

Actually, maybe we can rename$message to$envelope in this example? PHP allows us to do so (i.e. variable names not to match with the name in the interface). It might be clearer.

Yes. Please rename this.

if $message->get(MyMessage::class) is null, does it mean that this message is NOT originally a MyMessage isntance, right?

There is mis interpretation here. TheReceivedMessage class is not an example here, it's an actual envelope item within the component has is a marker that represents that the message has just been received. It's needed to have the router middleware ignoring them (otherwise we would have a receive -> send) loop.

Or, could you also pass something like $message->get(SerializerConfiguration::class) to get those types of things out?

That's notalso, that's the only thing you can do :)

how could I both perform my action only when the message is "received" AND only check the class of the original message

if (nul !==$message->get(ReceivedMessage::class) &&$message->getMessage()instanceof YourOwnMessageClass) {// Your logic...}

Might be clearer if werename$message to$envelope?