Documentation improvement suggestions

[gubler]

I wanted to give Prooph a try (I have use SimpleBus previously), mainly for the QueryBus support. In trying to set up a test Symfony app, I ran into some problems with the documentation. It took me a while to get everything working, but when I was done, these were the issues I found with the documentation:

As this is my first interaction with the Prooph service bus and this Symfony bundle, I wanted to bring these to the maintainer's attention for review before I went through the hassle of creating a pull request. I don't know if I missed something or possibly didn't understand something and wanted to get feedback first.

1. When using message_detection: true, your commands/events/queries have to implement the Message interface.

This is not explained in the documentation and all of the other Prooph documentation I found describes using Messages or plain PHP objects, or even plain strings. I can see why message_detection would require you to pass objects for determining the message map, but I don't see why they have to implement the Message interface. Either way, this should be called out in the documentation.

2. Handlers/Listeners Service Declaration must be Public

While this is actually called out in the documentation, I missed it originally, and the code examples do not include the public: true in the service declarations. I think this should be added to the examples.

3. Installation instructions do not include installing react/promise

If you create a QueryBus and have not installed react/promise, you get an exception. I am guessing the reason react/promise is not a dependency (and only a dev-dependency) is so it is not installed if the user doesn't generate a QueryBus. There should be some documentation that if you are going to use a QueryBus, you have to manually require react/promise.

[UFOMelkor]

Thank you for addressing this!

1. When using message_detection: true, your commands/events/queries have to implement the Message interface.

A message must not use its FQCN as name. Therefore a message can implement Prooph\Common\Messaging\HasMessageName to provide its name. Actually the current implementation is tailored for Prooph\Common\Messaging\DomainMessage as we also call an init method if available.

Another option would be to fallback to the FQCN if the Prooph\Common\Messaging\HasMessageName is not implemented.

Either way, the current implementation requires classes to implement Prooph\Common\Messaging\Message for message detection, which is not necessary.

My thoughts: If HasMessageName is implemented, use it; if not, use the FQCN.
@lunetics What do you think?

2. Handlers/Listeners Service Declaration must be Public

See #61. I'll hope to have a little bit free time this week (but more likely at the beginning of the next week) to ship this as v1.0.
But the documentation must be changed anyway. Correct will be: Handlers can be private.

3. Installation instructions do not include installing react/promise

👍
Should be also added as suggested dependency to composer.

[UFOMelkor]

I remembered why we allow message detection only for messages that implements HasMessageName: We need a way to identify a method as message handler. A message handler might have other methods which should not be setup as handlers.
To be detected methods …

• must have a first parameter which implements HasMessageName.
• may have a second parameter (necessary for query bus).

This way we can minimize the false positives. Currently I don't see another way to do this. If anyone has one, please share. Until then we should document this decision.

[prolic]

Should be also added as suggested dependency to composer.

I think that's the problem, as soon as composer install has been running, you get tons of suggestions from all the packages you've installed, and noone cares. So explaining this specifically in the docs is a huge bonus.

[prolic]

@UFOMelkor about handler method detection: I would suggest that if __invoke is present, that's the right method to use. If it's not available, then we may need to go with HasMessageName interface as first parameter in a public method.