Thanks @weaverryan. Updated based on your feedbacks 👍

Do we really need this functionality. SRP anyone?

@mvrhov : I'm not found of it either, but this can be useful for event buses. -> I was more thinking about the priority, not really handling multiple messages types in one handler. Sorry.

But for other types of buses, I'd personally prefer explicit psr-4 wiring rather than using a marker interface for auto configuration (and for which the getHandledMessages would basically be useless), like I'm already used to with tactician:

    command_handlers:
        namespace: App\Application\
        resource: '%kernel.project_dir%/src/Application/**/Handler/*CommandHandler.php'
        tags:
            - { name: tactician.handler, typehints: true, bus: command }

@ogizanagi which you can do already (except the multi-bus, for now) 🙃

services:
    App\Message\CommandHandler\:
        resource: '../src/Message/CommandHandler/*'
        tags: ['messenger.message_handler']

Source: https://github.com/Nyholm/message-component-demo/blob/master/config/services.yaml#L27-L29.

Of course! 😄
Just saying I find this interface too much constraining if you want to use it for autoconfiguration without psr-4 wiring, as it requires implementing a method that wouldn't be useful for most buses (and even for event buses, handling multiple event types in the same handler does not looks so nice to me. I was more referring to the priority in my previous comment actually).
Hence, I find the intent here not very clear.

Yea, the purpose of this is basically to support autoconfiguration. This particular interface (which is optional of course), is just the best way we could think of to make that happen :). We thought about doing a PSR-4 directory thing (like was suggested a few times, e.g. #26685 (comment)), but it gets a bit trickier, as we can't guarantee a user will have this in their services.yaml, unless we add it there always in the FrameworkBundle recipe... which is kinda weird since the config isn't relevant unless you install the component.

My suggestion would be if we need the interface, then Create a blank one as a marker. Then for those who would like to also handle multiple messages in one handler add another interface which extends the marker one.

We now have a pending PR for a Messenger recipe. So the PSR-4 directory loading could be added here.

Otherwise, I'd also recommend a blank marker interface.

Using psr4 directory loading is great. I’ve been using it for about 3 years with SimpleBus (not officially supported). However, I found it hard to explain and show for people consulting my project and for new developers. Having an alternative way of configure handlers that is very (!) similar to an existing pattern (EventSubsriberInterface) does make sense.

Also, I’ve noticed that I many times found myself wanting to have multiple messages handled in the same handler.

Say I have messages UploadedCoverImage and UploadedProfileImage should both be processed by the CleanMetadataHandler. Sure the “correct” way is to create a service and is used by CleanProfileMetadataHandler and CleanCoverMetadataHandler. But you know... using the same handler is more convenient and simple if the alternative is to create two empty handlers.

I'm not sure that there is any value of having an empty interface (well, except the fancyness of having it "autoconfigured", while PSR-4 discovery is doing the job).

On the other hand, it's almost the only way to be able to listen to multiple messages from the same handler. A side effect is actually that now it is auto-configurable.

I guess that taking this angle is much simpler to answer "is it necessary" and "should we do it this way".

I don't see why we should introduce the possiblity to handle different messages in the same handler, if we know, like @Nyholm said, the better solution is to have two handlers that share the same logic, e.g. with a service or a trait.
This also loses the possiblity to typehint the arguments of the __invoke method, which to me was the main reason why handlers are just callables instead of implementing an interface.

So to solve autoconfiguration I would prefer an empty marker interface for now. And if we need multiple messages support, we can still introduce a new interface that extends from the marker interface later.

I know but as I pointed out the additional thing is worse. So no point in adding something that is inferior.

I agree with @Tobion and @ogizanagi, 👍 for a marker only.

Can somebody give a good reason for adding support for handling multiple messages again? I thought several core members already said that there is no need for this?

@Nyholm has some use cases for it from his personal experience. But, it was certainly not a requirement - so we ended up at a compromise in this PR, with the empty interface + another optional one to support handling multiple messages.

I just used this feature in a project yesterday: this example was a "process manager". The idea is to listen to multiple messages (in the case of an event bus) and send them somewhere more or less generic (on a given aggregate) to be handled. That was great just because of this interface.

The argument wasn't that there is no use-case. It is that there is a better solution already so doesn't need to be solved at the framework level at all.

Also I don't see why the interface does not allow to specify the callback methods for the messages like EventSubscriberInterface. This would actually add a feature and make it more consistent.
Currently it just adds an inferior solution for a bad architectural design where you need to expose public methods without typing the arguments.

It is that there is a better solution already so doesn't need to be solved at the framework level at all.

I don't get your point. For this use-case, what would be "the better solution" then?

Also I don't see why the interface does not allow to specify the callback methods for the messages like EventSubscriberInterface

I don't believe this is actually required but I'd 👍 such a PR tbh.

Currently it just adds an inferior solution for a bad architectural design where you need to expose public methods without typing the arguments.

That's very subjective 😄 Here's one of my real-life message subscriber that I'd quite happy about:

class NotificationsManager implements MessageSubscriberInterface
{
    // ...

    public static function getHandledMessages(): array
    {
        return [
            PictureUploaded::class,
            TravelCreated::class,
        ];
    }

    public function __invoke(TravelEvent $event)
    {
        $travel = $this->travelRepository->find($event->getTravelUuid());
        $events = $travel->apply($event);

        foreach ($events as $raisedEvent) {
            $this->eventStore->append(Stream::fromTravel($travel), $raisedEvent);
        }
    }
}

In your case the handler processes messages that share a common parent (or interface), e.g. TravelEvent. I would suggest the messages should be routed to the handler automatically based on the type in __invoke. So getHandledMessages should not be necessary at all. So I think routing with instanceof should be supported in https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Messenger/HandlerLocator.php or a different implementation of HandlerLocatorInterface

The other case is that different messages that don't share a parent or interface are handled in the same handler. For this the following would already be supported and solve it at the language level instead of the framework level:

class NotificationMessageAHandler implements MessageHandlerInterface
{
    use NotificationHandlerTrait;

    public function __invoke(MessageA $msg)
    {
        $this->handle($msg); // whatever the trait exposes
    }
}

class NotificationMessageBHandler implements MessageHandlerInterface
{
    use NotificationHandlerTrait;

    public function __invoke(MessageB $msg)
    {
        $this->handle($msg); // whatever the trait exposes
    }
}

I would suggest the messages should be routed to the handler automatically based on the type in __invoke. So getHandledMessages should not be necessary at all. So I think routing with instanceof should be supported

or just explicit config 🙄

+1 for the trait example.

allow specifying the callback methods for the messages like EventSubscriberInterface

I think this is actually a very good idea: the current design of MessageSubscriberInterface forces using __invoke while allowing several methods would encourage proper type-hinting (instead of having to drop type hints entirely when using __invoke.)

But then we're back to something what's done already using individual handlers. Tend to like handlers being invokables from an architecture pov. Then again no real reason to force it i guess.

allow specifying the callback methods for the messages like EventSubscriberInterface

Yes. Just the consistency argument is IMHO enough to add this.

So I think routing with instanceof should be supported

Agree with you @Tobion.

The other case is that different messages that don't share a parent or interface are handled in the same handler

That's where I believe that this two-class + trait approach is not ideal in terms of DX. It isn't a bad practice either, if you know what you are doing and don't handle all your messages in the same sort of "mass handler".

I'm coming into this as a relative outsider - having only really jumped into this component from reviewing some PRs for symfony/docs.

I was surprised that there was no autoconfiguration from the interface and that it didn't end up using an API similar to EventSubscriberInterface with getSubscribedEvents() returning something like: array('eventName' => array(array('methodName1', $priority), array('methodName2')). I would 👍 towards something like this for consistency!

I'm not sure how that would work to continue support for the current option of just returning an array of classes as that's not something the EventSubscriberInterface supports.

Thank you for your feedback. It's not the first time it has been asked so here is the pull-request: #27034.

What are thoughts on a "supports" method where we could put instance of checks? Using @sroze's example above:

class NotificationsManager implements ???
{
    // ...

    public function supportsMessage($message): bool
    {
        return $message instanceof TravelEvent;
    }

    public function __invoke(TravelEvent $event)
    {
        $travel = $this->travelRepository->find($event->getTravelUuid());
        $events = $travel->apply($event);

        foreach ($events as $raisedEvent) {
            $this->eventStore->append(Stream::fromTravel($travel), $raisedEvent);
        }
    }
}

This would not require the handler to be aware of all possible types of message.