Envelopes & Stamps

With a Subscription, click any sentence in the script to jump to that part of the video!

We just got a request from Ponka herself... and when it comes to this site, Ponka is the boss. She thinks that, when a user uploads a photo, her image is actually being added a little bit too quickly. She wants it to take longer: she wants it to feel like she's doing some really epic work behind the scenes to get into your photo.

I know, it's kind of a silly example - Ponka is so weird when you talk to her before her shrimp breakfast and morning nap . But... it is an interesting challenge: could we somehow not only say: "handle this later"... but also "wait at least 5 seconds before handling it?".

Envelope: A Great Place to put a Message

Yep! And it touches on some super cool parts of the system called stamps and envelopes. First, open up ImagePostController and go up to where we create the AddPonkaToImage object. AddPonkaToImage is called the "message" - we know that. What we don't know is that, when you pass your message to the bus, internally, it gets wrapped inside something called an Envelope.

Now, this isn't an especially important detail except that, if you have an Envelope, you can attach extra config to it via stamps. So yes, you literally put a message in an envelope and then attach stamps. Is this your favorite component or what?

Anyways, those stamps can carry all sorts of info. For example, if you're using RabbitMQ, you can configure a few things about how the message is delivered, like something called a "routing key". Or, you can configure a delay.

Put the Message into the Envelope, then add Stamps

Check this out: say $envelope = new Envelope() and pass it our $message. Then, pass this an optional second argument: an array of stamps.

            
            100 lines
            
            src/Controller/ImagePostController.php
        
                                                    ... lines 1 - 15
                            
            use Symfony\Component\Messenger\Envelope;
        
                                                    ... lines 17 - 23
                            
            class ImagePostController extends AbstractController
        
            {
        
                                                    ... lines 26 - 40
                            
                public function create(Request $request, ValidatorInterface $validator, PhotoFileManager $photoManager, EntityManagerInterface $entityManager, MessageBusInterface $messageBus)
        
                {
        
                                                    ... lines 43 - 63
                            
                    $envelope = new Envelope($message, [
        
                                                    ... line 65
                            
                    ]);
        
                                                    ... lines 67 - 69
                            
                }
        
                                                    ... lines 71 - 98
                            
            }

Include just one: new DelayStamp(5000). This indicates to the transport... which is kind of like the mail carrier... that you'd like this message to be delayed 5 seconds before it's delivered. Finally, pass the $envelope - not the message - into $messageBus->dispatch().

            
            100 lines
            
            src/Controller/ImagePostController.php
        
                                                    ... lines 1 - 17
                            
            use Symfony\Component\Messenger\Stamp\DelayStamp;
        
                                                    ... lines 19 - 23
                            
            class ImagePostController extends AbstractController
        
            {
        
                                                    ... lines 26 - 40
                            
                public function create(Request $request, ValidatorInterface $validator, PhotoFileManager $photoManager, EntityManagerInterface $entityManager, MessageBusInterface $messageBus)
        
                {
        
                                                    ... lines 43 - 63
                            
                    $envelope = new Envelope($message, [
        
                        new DelayStamp(5000)
        
                    ]);
        
                    $messageBus->dispatch($envelope);
        
                                                    ... lines 68 - 69
                            
                }
        
                                                    ... lines 71 - 98
                            
            }

Yep, the dispatch() method accepts raw message objects or Envelope objects. If you pass a raw message, it wraps it in an Envelope. If you do pass an Envelope, it uses it! The end result is the same as before... except that we're now applying a DelayStamp.

Let's try it! This time we don't need to restart our worker because we haven't changed any code it will use: we only changed code that controls how the message will be delivered. But... if you're ever not sure - just restart it.

I will clear the console so we can watch what happens. Then... let's upload three photos and... one, two, three, four there it is! It delayed 5 seconds and then started processing each like normal. There's not a 5 second delay between handling each message: it just makes sure that each message is handled no sooner than 5 seconds after sending it.

Tip

Support for delays in Redis WAS added in Symfony 4.4.

Side note: In Symfony 4.3, the Redis transport doesn't support delays - but it may be added in the future.

What other Stamps are There?

Anyways, you may not use stamps a ton, but you will need them from time-to-time. You'll probably Google "How do I configure validation groups in Messenger" and learn which stamp controls this. Don't worry, I'll talk about validation later - it's not something that's happening right now.

One other cool thing is that, internally, Messenger itself uses stamps to track and help deliver messages correctly. Check this out: wrap $messageBus->dispatch() in a dump() call.

            
            100 lines
            
            src/Controller/ImagePostController.php
        
                                                    ... lines 1 - 23
                            
            class ImagePostController extends AbstractController
        
            {
        
                                                    ... lines 26 - 40
                            
                public function create(Request $request, ValidatorInterface $validator, PhotoFileManager $photoManager, EntityManagerInterface $entityManager, MessageBusInterface $messageBus)
        
                {
        
                                                    ... lines 43 - 66
                            
                    dump($messageBus->dispatch($envelope));
        
                                                    ... lines 68 - 69
                            
                }
        
                                                    ... lines 71 - 98
                            
            }

Let's go over and upload one new image. Then, on the web debug toolbar, find the AJAX request that just finished - it'll be the bottom one - click to open its profiler and then click "Debug" on the left. There it is! The dispatch() method returns an Envelope... which holds the message of course... and now has four stamps! It has the DelayStamp like we expected, but also a BusNameStamp, which records the name of the bus that it was sent to. This is cool: we only have one bus now, but you're allowed to have multiple, and we'll talk about why you might do that later. The BusNameStamp helps the worker command know which bus to send the Envelope to after it's read from the transport.

That SentStamp is basically a marker that says "this message was sent to a transport instead of being handled immediately" and this TransportMessageIdStamp, literally contains the id of the new row in the messenger_messages table... in case that's useful.

You don't really need to care about any of this - but watching what stamps are being added to your Envelope may help you debug an issue or do some more advanced stuff. In fact, some of these will come in handy soon when we talk about middleware.

For now, remove the dump() and then, so I don't drive myself crazy with how slow this is, change the DelayStamp to 500 milliseconds. Shh, don't tell Ponka. After this change... yep! The message is handled almost immediately.

            
            100 lines
            
            src/Controller/ImagePostController.php
        
                                                    ... lines 1 - 23
                            
            class ImagePostController extends AbstractController
        
            {
        
                                                    ... lines 26 - 40
                            
                public function create(Request $request, ValidatorInterface $validator, PhotoFileManager $photoManager, EntityManagerInterface $entityManager, MessageBusInterface $messageBus)
        
                {
        
                                                    ... lines 43 - 63
                            
                    $envelope = new Envelope($message, [
        
                        new DelayStamp(500)
        
                    ]);
        
                    $messageBus->dispatch($envelope);
        
                                                    ... lines 68 - 69
                            
                }
        
                                                    ... lines 71 - 98
                            
            }

Next, let's talk about retries and what happens when things go wrong! No joke: this stuff is super cool.

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": "^7.1.3",
        "ext-ctype": "*",
        "ext-iconv": "*",
        "composer/package-versions-deprecated": "^1.11", // 1.11.99
        "doctrine/annotations": "^1.0", // v1.8.0
        "doctrine/doctrine-bundle": "^1.6.10", // 1.11.2
        "doctrine/doctrine-migrations-bundle": "^1.3|^2.0", // v2.0.0
        "doctrine/orm": "^2.5.11", // v2.6.3
        "intervention/image": "^2.4", // 2.4.2
        "league/flysystem-bundle": "^1.0", // 1.1.0
        "phpdocumentor/reflection-docblock": "^3.0|^4.0", // 4.3.1
        "sensio/framework-extra-bundle": "^5.3", // v5.3.1
        "symfony/console": "4.3.*", // v4.3.2
        "symfony/dotenv": "4.3.*", // v4.3.2
        "symfony/flex": "^1.9", // v1.18.7
        "symfony/framework-bundle": "4.3.*", // v4.3.2
        "symfony/messenger": "4.3.*", // v4.3.4
        "symfony/property-access": "4.3.*", // v4.3.2
        "symfony/property-info": "4.3.*", // v4.3.2
        "symfony/serializer": "4.3.*", // v4.3.2
        "symfony/validator": "4.3.*", // v4.3.2
        "symfony/webpack-encore-bundle": "^1.5", // v1.6.2
        "symfony/yaml": "4.3.*" // v4.3.2
    },
    "require-dev": {
        "easycorp/easy-log-handler": "^1.0.7", // v1.0.7
        "symfony/debug-bundle": "4.3.*", // v4.3.2
        "symfony/maker-bundle": "^1.0", // v1.12.0
        "symfony/monolog-bundle": "^3.0", // v3.4.0
        "symfony/stopwatch": "4.3.*", // v4.3.2
        "symfony/twig-bundle": "4.3.*", // v4.3.2
        "symfony/var-dumper": "4.3.*", // v4.3.2
        "symfony/web-profiler-bundle": "4.3.*" // v4.3.2
    }
}

Edit on GitHub

TRACK

Symfony 5 >

COURSE

Messenger! Queue work for Later

Envelopes & Stamps

Keep on Learning!

Envelope: A Great Place to put a Message

Put the Message into the Envelope, then add Stamps

What other Stamps are There?

Leave a comment!

What PHP libraries does this tutorial use?

	... lines 1 - 15
	use Symfony\Component\Messenger\Envelope;
	... lines 17 - 23
	class ImagePostController extends AbstractController
	{
	... lines 26 - 40
	public function create(Request $request, ValidatorInterface $validator, PhotoFileManager $photoManager, EntityManagerInterface $entityManager, MessageBusInterface $messageBus)
	{
	... lines 43 - 63
	$envelope = new Envelope($message, [
	... line 65
	]);
	... lines 67 - 69
	}
	... lines 71 - 98
	}

	... lines 1 - 17
	use Symfony\Component\Messenger\Stamp\DelayStamp;
	... lines 19 - 23
	class ImagePostController extends AbstractController
	{
	... lines 26 - 40
	public function create(Request $request, ValidatorInterface $validator, PhotoFileManager $photoManager, EntityManagerInterface $entityManager, MessageBusInterface $messageBus)
	{
	... lines 43 - 63
	$envelope = new Envelope($message, [
	new DelayStamp(5000)
	]);
	$messageBus->dispatch($envelope);
	... lines 68 - 69
	}
	... lines 71 - 98
	}

	... lines 1 - 23
	class ImagePostController extends AbstractController
	{
	... lines 26 - 40
	public function create(Request $request, ValidatorInterface $validator, PhotoFileManager $photoManager, EntityManagerInterface $entityManager, MessageBusInterface $messageBus)
	{
	... lines 43 - 66
	dump($messageBus->dispatch($envelope));
	... lines 68 - 69
	}
	... lines 71 - 98
	}