Update reflection based abstract factory documentation #136
Conversation
After working through the documentation to learn more about it, I felt that the documentation could be refined to make it that much easier to read, as well as to extend the usage examples to make them more encompassing of different use cases. Signed-off-by: Matthew Setter <[email protected]>
The intention of this change is to make the file easier to maintain, rather than to have lines fit within a mandatory 72 - 80 char per/line limit. Personally, this new approach makes content easier to move around, to edit, and to remove as and when required, than arbitrary line lengths that break sentences midway across one or more lines. Signed-off-by: Matthew Setter <[email protected]>
Signed-off-by: Matthew Setter <[email protected]>
|
Note: IMO for |
I'm pretty sure @froschdesign recommended 3.11. @froschdesign? |
|
Unless it's a bugfix, it should be landing in new minors in general :D |
As already mentioned: with the current state of documentation, in terms of quality and quantity, any change can be considered as a patch. No matter if something is updated or added. |
|
I'd do a patch release even for docs, which is just more noise tho? 🤔 In this case, I'd do 2 releases + 2 merge-ups |
It would be much better if changes to documentation did not require releases at all. 😜 |
|
I don't mind, honestly - we don't have enough noise from it for it to be a problem. |
|
@Ocramius, if you don't mind either way, I'd prefer to leave it as is. On a different note, what can I do about the DCO check failing, as it relates to laminas bot? Just merge anyway? |
|
Yeah, DCO is useless corporateism, so it can be ignored on anything that isn't "world-changing tech", TBH. |
|
@froschdesign your call on where/how to merge/release |
| To alleviate this issue during development, laminas-servicemanager ships with the `ReflectionBasedAbstractFactory`, which provides a [reflection-based approach](https://www.php.net/manual/en/intro.reflection.php) to instantiation, resolving constructor dependencies to the relevant services. | ||
| The factory may be used as either an abstract factory or mapped to specific service names as a factory. | ||
|
|
||
| TIP: Mapping services to the factory is more explicit and performant. |
There was a problem hiding this comment.
I would move the tip to the end of this section.
| TIP: Mapping services to the factory is more explicit and performant. |
| - If a service cannot be found for a given typehint, the factory will raise an exception detailing this. | ||
|
|
||
| WARNING: `$options` passed to the factory are ignored in all cases, as we cannot make assumptions about which argument(s) they might replace. |
There was a problem hiding this comment.
The list is introduced with "features" and "constraints" therefore this warning can be a normal list entry:
| - If a service cannot be found for a given typehint, the factory will raise an exception detailing this. | |
| WARNING: `$options` passed to the factory are ignored in all cases, as we cannot make assumptions about which argument(s) they might replace. | |
| - If a service cannot be found for a given typehint, the factory will raise an exception detailing this. | |
| - `$options` passed to the factory are ignored in all cases, as we cannot make assumptions about which argument(s) they might replace. |
|
|
||
| TIP: Mapping services to the factory is more explicit and performant. | ||
|
|
||
| The factory operates with the following constraints/features: |
There was a problem hiding this comment.
The positive first:
| The factory operates with the following constraints/features: | |
| The factory operates with the following features/constraints: |
| ### Using Laminas MVC | ||
|
|
||
| When using [Laminas MVC](https://docs.laminas.dev/mvc/): |
There was a problem hiding this comment.
The package name for laminas-mvc is used most and is also the preferred way so far.
(If something refers to Mezzio, then the spelling with a capital initial is used: "Mezzio". The package names also follow the names used in Composer. Example: "mezzio-problem-details".)
| ### Using Laminas MVC | |
| When using [Laminas MVC](https://docs.laminas.dev/mvc/): | |
| ### Using laminas-mvc | |
| When using [laminas-mvc](https://docs.laminas.dev/mvc/): |
| - Add the factory in the service manager's list of abstract factories. | ||
| - Use the `ReflectionBasedAbstractFactory` to instantiate the class. |
There was a problem hiding this comment.
This part and also the code example are wrong because you do not need both options to use ReflectionBasedAbstractFactory.
- If the
ReflectionBasedAbstractFactoryis used as an abstract factory, then it will do the job for all services to which no explicit factory is mapped. - If the
ReflectionBasedAbstractFactoryis used as factory for a single service, then it will work only for this one service.
This means that we need two independent examples for the documentation, each with its own explanation!
| - Add the `ReflectionBasedAbstractFactory` to the `abstract_factories` array returned from the `getDependencies()` method. | ||
| - Use the `ReflectionBasedAbstractFactory` to instantiate the class, in the `factories` array returned from the `getDependencies()` method. | ||
|
|
||
| Once your dependencies have stabilized, we recommend writing a dedicated | ||
| factory, as reflection can introduce performance overhead; you may use the | ||
| [generate-factory-for-class console tool](console-tools.md#generate-factory-for-class) | ||
| to do so. | ||
| ```php | ||
| use Laminas\ServiceManager\AbstractFactory\ReflectionBasedAbstractFactory; | ||
|
|
||
| public function getDependencies(): array | ||
| { | ||
| return [ | ||
| 'abstract_factories' => [ | ||
| ReflectionBasedAbstractFactory::class, | ||
| ], | ||
| 'factories' => [ | ||
| // Other factories... | ||
| Handler\HomePageHandler::class => ReflectionBasedAbstractFactory::class, | ||
| ], | ||
| ], | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The same as above: this is wrong.
| Once your dependencies have stabilized and when performance is a requirement, we recommend writing a dedicated factory, as reflection can introduce performance overhead. | ||
| For example, you could use the [generate-factory-for-class console tool](console-tools.md#generate-factory-for-class) to do so. |
There was a problem hiding this comment.
I would suggest adding the tip here:
| Once your dependencies have stabilized and when performance is a requirement, we recommend writing a dedicated factory, as reflection can introduce performance overhead. | |
| For example, you could use the [generate-factory-for-class console tool](console-tools.md#generate-factory-for-class) to do so. | |
| TIP: Once your dependencies have stabilized and when performance is a requirement, we recommend writing a dedicated factory, as reflection can introduce performance overhead. | |
| For example, you could use the [generate-factory-for-class console tool](console-tools.md#generate-factory-for-class) to do so. |
|
@settermjd @froschdesign I've also modified the documentation in #180 Should we try to finish this as well and then merge-up to 4.0.x? |
A good idea, because the entire documentation needs to be reworked for version 4.0. |
Description
After working through the documentation to learn more about the Reflection-based Abstract Factor, I felt that the documentation could be refined to make it that much easier to read and maintain, as well as to extend the usage examples to make them more encompassing of different use cases. This PR replaces #134.