[Messenger][DX] Uses custom method names for handlers #27034

sroze · 2018-04-24T16:40:34Z

Q	A
Branch?	master
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	#26685 (comment)
License	MIT
Doc PR	ø

This has been discussed mostly in the MessageHandlerInterface pull-request. For consistency reasons and convenience, this PR adds the ability to configure the method to be used on handlers:

use Symfony\Component\Messenger\Handler\MessageSubscriberInterface;
use Symfony\Component\Messenger\Handler\MessageSubscriberConfiguration;

class CreateNumberMessageHandler implements MessageSubscriberInterface
{
    /**
     * {@inheritdoc}
     */
    public static function getHandledMessages(): array
    {
        return [
            CreateNumber::class => ['createNumber', 10],
            AnotherMessage::class => 'anotherMethod',
        ];
    }

    public function createNumber(CreateNumber $command)
    {
        // ...
    }
}

ogizanagi

MessageSubscriberInterface::getHandledMessages docblock misses an update

ogizanagi · 2018-04-24T17:07:13Z

src/Symfony/Component/Messenger/Handler/MethodOnObjectHandler.php

+/**
+ * Used to transform an object and a method to a callable handler.
+ *
+ * @author Samuel Roze <samuel.roze@gmail.com>


@internal ?

Good point, added 👍

ogizanagi · 2018-04-24T17:17:33Z

src/Symfony/Component/Messenger/DependencyInjection/MessengerPass.php

        $handlersByMessage = array();

        foreach ($container->findTaggedServiceIds($this->handlerTag, true) as $serviceId => $tags) {
            foreach ($tags as $tag) {
-                $handles = isset($tag['handles']) ? array($tag['handles']) : $this->guessHandledClasses($r = $container->getReflectionClass($container->getDefinition($serviceId)->getClass()), $serviceId);
+                if (isset($tag['handles'])) {
+                    $handles = isset($tag['method']) ? array($tag['handles'] => $tag['method']) : array($tag['handles']);


Should it check the method exists to warn about typos at compile time?

chalasr · 2018-04-24T17:38:23Z

src/Symfony/Component/Messenger/DependencyInjection/MessengerPass.php

                $priority = $tag['priority'] ?? 0;

-                foreach ($handles as $messageClass) {
+                foreach ($handles as $messageClass => $method) {
+                    if (is_int($messageClass)) {


let's add a \ in front of is_* calls to be consistent with the existing one below

chalasr · 2018-04-24T17:38:33Z

src/Symfony/Component/Messenger/Handler/MethodOnObjectHandler.php

+    public function __construct($object, string $method)
+    {
+        if (!is_object($object)) {
+            throw new \InvalidArgumentException(sprintf('Expected an object as argument but got %s', gettype($object)));


\is_object, \gettype (no, I'm not a bot :))

Tobion · 2018-04-24T20:09:23Z

src/Symfony/Component/Messenger/DependencyInjection/MessengerPass.php

+                    if ('__invoke' !== $method) {
+                        $wrapperDefinition = (new Definition(MethodOnObjectHandler::class))->setArguments(array(new Reference($serviceId), $method));
+
+                        $definitions[$serviceId = hash('sha1', $messageClass.':'.$messagePriority.':'.$serviceId)] = $wrapperDefinition;


It looks like it does not work for

public static function getHandledMessages(): array { return [ CreateNumber::class => 'method', CreateNumber::class => 'anotherMethod', ]; }

also, please use ContainerBuilder::hash instead of sha1

@Tobion Your array does not work. It has a single item in it as PHP does not allow duplicate keys.

however, the hash should indeed include the method name, as you can have multiple methods.

and the final service id should not be only the hash. It should have a prefix before it to make it easier to identify services in error message (messenger.method_object_handler.<hash> could make sense)

Good point, method should be in the hash. Updated 👍

Tobion · 2018-04-27T00:05:44Z

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.

sroze · 2018-04-27T06:53:23Z

I like it!

sroze · 2018-04-27T09:20:19Z

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

Tobion · 2018-04-27T09:44:43Z

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);
    }

nicolas-grekas · 2018-04-27T09:53:59Z

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?

Tobion · 2018-04-27T09:56:59Z

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

sroze · 2018-04-27T09:57:58Z

@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.

stof · 2018-04-27T10:40:53Z

@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.

nicolas-grekas · 2018-04-27T10:49:11Z

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 :) )

Tobion · 2018-04-27T11:03:44Z

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.

nicolas-grekas · 2018-04-27T11:10:20Z

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.

nicolas-grekas · 2018-04-29T06:26:43Z

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().

nicolas-grekas · 2018-05-03T14:46:12Z

@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.

sroze · 2018-05-03T14:47:26Z

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

sroze · 2018-05-04T08:33:25Z

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).

sroze · 2018-05-05T11:15:03Z

Shall we go ahead with this one?

ogizanagi

Yes, makes sense to me as is. Let's move forward 👍

nicolas-grekas · 2018-05-05T16:59:51Z

src/Symfony/Component/Messenger/DependencyInjection/MessengerPass.php

@@ -23,6 +23,7 @@
 use Symfony\Component\Messenger\Handler\MessageHandlerInterface;
 use Symfony\Component\Messenger\Handler\MessageSubscriberInterface;
 use Symfony\Component\Messenger\TraceableMessageBus;
+use Symfony\Component\Messenger\Handler\MethodOnObjectHandler;


Alpha order

updated 👍

nicolas-grekas · 2018-05-05T17:05:43Z

src/Symfony/Component/Messenger/DependencyInjection/MessengerPass.php

+                    if ('__invoke' !== $method) {
+                        $wrapperDefinition = (new Definition(MethodOnObjectHandler::class))->setArguments(array(new Reference($serviceId), $method));
+
+                        $definitions[$serviceId = 'messenger.method_on_object_handler.'.ContainerBuilder::hash($messageClass.':'.$messagePriority.':'.$serviceId.':'.$method)] = $wrapperDefinition;


Missing dot at start of service is.

But can't we pass array($def, $method) instead of using this handler?

Not the way it's done now because we simply wire the handlers (i.e. callables). That way is also simpler :)

nicolas-grekas · 2018-05-06T14:28:12Z

src/Symfony/Component/Messenger/DependencyInjection/MessengerPass.php

+                    }
+
+                    if ('__invoke' !== $method) {
+                        $wrapperDefinition = (new Definition(MethodOnObjectHandler::class))->setArguments(array(new Reference($serviceId), $method));


$wrapperDefinition = (new Definition('callable'))->addArgument(array(new Reference($serviceId), $method))->setFactory('Closure::fromCallable');
cheers :)

fabpot · 2018-05-07T13:01:13Z

src/Symfony/Component/Messenger/DependencyInjection/MessengerPass.php

+                        $messageClass = $method;
+                        $method = '__invoke';
+                    }
+
                    if (\is_array($messageClass)) {


could be else if here, right?

Changed with elseif.

@fabpot actually can't because we are setting $messagePriority as well.

sroze · 2018-05-08T15:33:16Z

Status: Needs review

sroze · 2018-05-09T07:47:01Z

@fabpot could you update your review please?

@inheritdoc

…(sroze) This PR was merged into the 4.1 branch. Discussion ---------- [Messenger][DX] Uses custom method names for handlers | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #26685 (comment) | License | MIT | Doc PR | ø This has been discussed mostly in the [`MessageHandlerInterface` pull-request](#26685). For consistency reasons and convenience, this PR adds the ability to configure the method to be used on handlers: ```php use Symfony\Component\Messenger\Handler\MessageSubscriberInterface; use Symfony\Component\Messenger\Handler\MessageSubscriberConfiguration; class CreateNumberMessageHandler implements MessageSubscriberInterface { /** * {@inheritdoc} */ public static function getHandledMessages(): array { return [ CreateNumber::class => ['createNumber', 10], AnotherMessage::class => 'anotherMethod', ]; } public function createNumber(CreateNumber $command) { // ... } } ``` Commits ------- 2461e51 [Messenger][DX] Uses custom method names for handlers

carsonbot added Status: Needs Review DX DX = Developer eXperience (anything that improves the experience of using Symfony) Feature labels Apr 24, 2018

sroze force-pushed the messenger-handler-with-custom-method branch from 03e2a89 to f9c1e0d Compare April 24, 2018 16:42

sroze mentioned this pull request Apr 24, 2018

[Messenger] Add a MessageHandlerInterface (multiple messages + auto-configuration) #26685

Merged

sroze added the Messenger label Apr 24, 2018

ogizanagi reviewed Apr 24, 2018

View reviewed changes

chalasr reviewed Apr 24, 2018

View reviewed changes

chalasr added this to the 4.1 milestone Apr 24, 2018

sroze force-pushed the messenger-handler-with-custom-method branch from e6abce2 to 06f1eae Compare April 24, 2018 18:25

chalasr approved these changes Apr 24, 2018

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Review labels Apr 24, 2018

ogizanagi approved these changes Apr 24, 2018

View reviewed changes

Tobion reviewed Apr 24, 2018

View reviewed changes

sroze force-pushed the messenger-handler-with-custom-method branch from 908fe56 to 99e8cb5 Compare April 25, 2018 20:18

yceruto mentioned this pull request Apr 27, 2018

[Messenger] Configure a handler to subscribe to messages by their interface/parent class #27076

Closed

kbond mentioned this pull request Apr 27, 2018

[Messenger] make return type of MessageSubscriberInterface::getHandledMessages() iterable #27082

Closed

sroze force-pushed the messenger-handler-with-custom-method branch from e23faea to a5a2a75 Compare May 4, 2018 08:29

ogizanagi approved these changes May 5, 2018

View reviewed changes

nicolas-grekas reviewed May 5, 2018

View reviewed changes

sroze force-pushed the messenger-handler-with-custom-method branch from 0ddb2d1 to 5fab1d7 Compare May 6, 2018 14:05

nicolas-grekas reviewed May 6, 2018

View reviewed changes

ogizanagi mentioned this pull request May 6, 2018

[DI] Allow binding by type+name #27165

Merged

fabpot requested changes May 7, 2018

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Reviewed labels May 7, 2018

sroze force-pushed the messenger-handler-with-custom-method branch from edd0e4b to 8927224 Compare May 7, 2018 13:55

nicolas-grekas changed the base branch from master to 4.1 May 7, 2018 15:05

kbond mentioned this pull request May 7, 2018

[RFC][Messenger] add MessageInstanceOf helper #27188

Closed

sroze force-pushed the messenger-handler-with-custom-method branch from 8927224 to f711250 Compare May 8, 2018 15:27

carsonbot added Status: Needs Review and removed Status: Needs Work labels May 8, 2018

carsonbot removed the Status: Needs Review label May 11, 2018

fabpot approved these changes May 11, 2018

View reviewed changes

carsonbot added the Status: Reviewed label May 11, 2018

fabpot force-pushed the messenger-handler-with-custom-method branch from f711250 to 5470fcf Compare May 11, 2018 12:07

[Messenger][DX] Uses custom method names for handlers

2461e51

sroze force-pushed the messenger-handler-with-custom-method branch from 5470fcf to 2461e51 Compare May 11, 2018 13:03

sroze merged commit 2461e51 into symfony:4.1 May 11, 2018

fabpot mentioned this pull request May 21, 2018

Release v4.1.0-BETA2 #27331

Merged

[Messenger][DX] Uses custom method names for handlers #27034

[Messenger][DX] Uses custom method names for handlers #27034

Conversation

sroze commented Apr 24, 2018 • edited Loading

ogizanagi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chalasr Apr 24, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Tobion commented Apr 27, 2018 • edited Loading

sroze commented Apr 27, 2018

sroze commented Apr 27, 2018

Tobion commented Apr 27, 2018 • edited Loading

nicolas-grekas commented Apr 27, 2018

Tobion commented Apr 27, 2018

sroze commented Apr 27, 2018 • edited Loading

stof commented Apr 27, 2018

nicolas-grekas commented Apr 27, 2018

Tobion commented Apr 27, 2018 • edited Loading

nicolas-grekas commented Apr 27, 2018 • edited Loading

nicolas-grekas commented Apr 29, 2018

nicolas-grekas commented May 3, 2018

sroze commented May 3, 2018

sroze commented May 4, 2018

sroze commented May 5, 2018

ogizanagi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nicolas-grekas May 6, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sroze May 7, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sroze commented May 8, 2018

sroze commented May 9, 2018

sroze commented Apr 24, 2018 •

edited

Loading

chalasr Apr 24, 2018 •

edited

Loading

Tobion commented Apr 27, 2018 •

edited

Loading

Tobion commented Apr 27, 2018 •

edited

Loading

sroze commented Apr 27, 2018 •

edited

Loading

Tobion commented Apr 27, 2018 •

edited

Loading

nicolas-grekas commented Apr 27, 2018 •

edited

Loading

nicolas-grekas May 6, 2018 •

edited

Loading

sroze May 7, 2018 •

edited

Loading