From my experience the EventSubscriber return value to configure callbacks has a really bad DX. It's not clear what array structure can be returned without reading the doc. Repeating that in the MessageSubscriberInterface seems bad to me.

How about using a value object like

    public static function getHandledMessages(): array
    {
        return [
            new MessageCallback(CreateNumber::class, 'createNumber', 10),
            new MessageCallback(AnotherMessage::class, 'anotherMethod'),
        ];
    }

class MessageCallback
{
    public function __construct(string $messageClass, string $method = '__invoke', int $priority = 0)
    {
    }
}

This way the code is self-explaining and you don't have to deal with mixed returns like array of array or array of string or non-associative array.

I like it!

But the point of this PR is actually to make it consistent with the EventSubscriber to improve the developer experience 🙃

Learning from mistakes and improving them seems more important to me. Also the EventSubscriber with it's array structure is probably not gonna make it like this into the EventDispatcher PSR that got revived. But something like my propal is really flexible and clear. Just make MessageCallback an interface with getters and voila.
I would also suggest to make the return value iterable instead of array.
I could imagine an implementation that just configures all public methods of the subscriber as handlers with the typehints (similar to the __invoke autowiring but for several methods).

    public static function getHandledMessages(): iterable
    {
        return new PublicMethodsAsHandlers(self::class);
    }

public static function getHandledMessages(): HandledMessagesDescription
return (new HandledMessagesDescription())->someFluentApi()...?

but this looks like a lot of code infrastructure, which means this works only with a compiled container, because when not compiled the overhead of building this configuration can become significant, especially compared to the array approach, isn't it?

I don't see where the overhead is when using a value object or a fluent api? This is just setters and getters.

@nicolas-grekas I prefer the array approach (with the MessageCallback - or similar name - value object) than the fluent API as it's much simpler for everybody, to use, understand and maintain. There isn't anything complex to build here that requires a fluent API I believe.

I like the return new PublicMethodsAsHandlers(self::class); example also.

@sroze the array of EventSubscriberInteface is very simple when you have to register a single listener. But when you need to register 2 listeners for the same event, I admit that I get it wrong half of the time (doing array('foo', 'bar') instead of array(array('foo'), array('bar')). I even went as far as writing a unit test taking all my subscribers and validating the structure being returned.

Would it make sense to use the static method as a configurator?

static function configureHandledMessages(HandledMessagesDescriptor $config)
{
    $config->...
}

BUT on the other end, any objects we put here tightly couples the interface to the descriptor.
It could be a blocker when taking interoperability into account: by forcing an object wrapper, we forbid any custom extension of the return value. An array doesn't have this drawback.
(just thinking loud :) )

One more idea that closes the circle in my eyes:

Remove https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Messenger/Handler/MessageHandlerInterface.php and instead offer a trait/abstract class that implements

public static function getHandledMessages(): iterable
{
    return [
        new ReflectedMethodCallback(self::class, '__invoke'),
    ];
}

This is self-explaining, does not require more code than implementing the marker interface and does not require a marker interface at all. A marker interface without methods is usually just a workaround anyway.

I think this is building infrastructure on top of conventions. We should design first and implement after IMHO.
Another issue with using objects is that it will make it much harder for IDEs to use the return value to provide auto-completion.
On a DX perspective, I really much prefer injecting the descriptor than have a "new" in the body of the method. The reason is that "new" forces to know what type to create; while passing by argument is just perfect for providing autocompletion.

Disclaimer: the arguments I'm giving here are done while taking the existing static method descriptions we already have. @Tobion uses the word "mistake" above, I'm really not sure this was a mistake at all. And more importantly, I want to be sure whatever new system we use is actually better.

As @Tobion spotted, using an injected argument enforces a single style of configuration (the DX is bound to the style provided byHandledMessagesDescriptor in my example above). While this can be nice for autocompletion, I don't think we can make a universal enough style (that could eg fit a FIG PSR - which is not a goal here, but still nice for guiding the thought).

I'm also not really convinced by returning objects, for similar reasons: a locally created object forces also a style, or if we make it an interface, the interface could only provide a way to retrieve the state of the configuration, without providing any contractual guarantee (unlike the injected argument btw).

For this reasons, I now think this method should return an array.
I also think we can provide a builder for this array if we want to, but this builder should be an (optional) implementation detail used in some implementations of getHandledMessages().

@sroze if you want to move forward here, I suggest to isolate things that are unrelated to the return format of the static method in another PR if that makes sense.

@nicolas-grekas i.e. revert to the array-notation, right?

Alright, that's fair that there are different point of views and it's a tricky question, therefore let's make that in two steps: I reverted the introduction of the VO and kept the array EventDispatcher-like syntax (while changing the getHandledMessages() signature to return a iterable rather than an array).

Shall we go ahead with this one?

Status: Needs review

@fabpot could you update your review please?