HTTPlug Maturity Model

[fbourigault]

Background

On Slack, while talking about PluginClientFactory documentation, I suggested refactoring the library developer documentation to make it a tutorial. Then @Nyholm suggested a HTTPlug Maturity Model inspired from Richardson Maturity Model.

Introduction

The idea is to write the HTTPlug Maturity Model as a tutorial, to guide library developer to go from a library depending on Guzzle to a decoupled library decoupled from the HttpClient implementation, decoupled from the Message implementation which use the discovery and use a PluginClient created using PluginClientFactory for zero config profiling.

HTTPlug Maturity Model

Level 0: hard dependency on guzzlehttp/guzzle

That's our starting point. The library is hardly depending on guzzlehttp/guzzle. We have to tell why it's bad and get the user continue reading to the next level.

Level 1: use of HttpClient interface

Here, the user will use the HttpClient interface to allow usage of any compatible library through adapters.

Level 2: use of factories

At this level, the user will use php-http/message to decouple from any message implementation.

Level 3: use of discovery

In 3rd level, the user will learn using the discovery for a better DX.

Level 4: use of PluginClient (with PluginClientFactory and Builder pattern)

At this level, we teach to the library developer how to support extra features like authentication using plugins. We also explain why he should use the PluginClientFactory to enable
zero config profiling when used in a Symfony application which use HttplugBundle.

Each level would expose a situation with a few code examples and at it's end expose the problem which will be solved in the next level (or tell we achieved our journey and have a mature HTTP decoupled library).

I also think we could create a 5th level split out from the 4th. This level could be dedicated to improving the DX by including the PluginClientFactory and builder pattern.

Conclusion

By writing this guide, I think we can teach developers how to write something awesome and can covers in a consolidated doc everything the library developer should know and also promote nice HTTPlug features.

Do you think it worth to be written?

[Nyholm]

👍 And also, It is fine to stay at each level. Maybe Im happy with my package just reaching level 2. That is very fine.

[sagikazarmark]

Nice. 👍

Personally I would leave discovery out, it's a convenience layer, breaks Inversion of Control, so mostly an anti-pattern. In any case, that should be the last level if not left out.

[fbourigault]

@sagikazarmark we can use discovery and still allow IoC (https://github.com/m4tthumphrey/php-gitlab-api/blob/master/lib/Gitlab/HttpClient/Builder.php#L65-L73). Maybe this could live in the DX level.

[dbu]

i disagree with level 3. it should talk about dependency injection instead, and then lead to level 4, to handle when you need specific plugins to be available. discovery is an antipatern in my eyes (though a popular one, see laravel). maybe have level 3 a and level 3 b to explain the two alternative approaches?

[sagikazarmark]

@fbourigault yes, but in this case discovery is a fallback. By default people should use dependency injection, and if they really-really want to put this extra thing into their package, they can make the constructor arguments optional (eg. allow null), and use discovery. It does not break the API.

So I would say, using discovery should always be a last step, one should not start writing software using discovery by default.

For example: when writing an API client to an internal API will probably never require that.