Update plugin documentation #104
Conversation
|
i added WCM to the title (waiting for code merge). content wise i agree, looks good. can you check travis-ci? |
| @@ -4,7 +4,7 @@ Building Custom Plugins | |||
| When writing your own Plugin, you need to be aware that the Plugin Client is async first. | |||
| This means that every plugin must be written with Promises. More about this later. | |||
|
|
|||
| Each plugin must implement the ``Http\Client\Plugin\Plugin`` interface. | |||
| Each plugin must implement the ``Http\Client\Common\Plugin`` interface. | |||
There was a problem hiding this comment.
this will only be correct once we have released 1.1 right? we might want to add a versionadded block in strategically relevant places to explain what was changed in 1.1
There was a problem hiding this comment.
What is versionadded?
There was a problem hiding this comment.
There was a problem hiding this comment.
And what would be the format? Since from the documentation point of view we haven't added anything, but changed. Would it be "Since client-common 1.1 Plugins are part of that package" or "Prior to client-common 1.1 it was a separate package"?
There was a problem hiding this comment.
There was a problem hiding this comment.
👍 I will add it.
One more though: we probably have to always mention the package as well, since the versioning is not aligned between repos.
There was a problem hiding this comment.
right, good point. so lets be even more explicit and say something like
The plugins where moved to the clients-common package in version 1.1. If
you work with version 1.0, you need to require the separate plugin
package. The new interface will keep implementing
Http\Client\Plugin\Plugin until version 2 but relying on the old
interface is deprecated.
There was a problem hiding this comment.
The new interface will keep implementing
Hm, this is not true, and even if it was, it should be the other way around IMO: the old interface should extend the new one.
sagikazarmark
force-pushed
the
plugin_relocation
branch
from
8bbdef4 to
63ca6be
Compare
but then we have a BC problem i think. if i wrote code with the old interface, it should keep working until we go to 2.0. so the new interface should extend the old interface. or did we say for this edge case we do a BC break? |
|
Technically, there is no BC break. The "old" plugin client is still available in the old plugin package. If you want to use the old plugins, you still can with the old client. What I could imagine is to extend the old plugin interface with the new one, so that old plugins work in the new client as well, but I don't think we have to maintain it vica versa (new plugins in the old client). There is already kind of a PR for that: php-http/plugins#64 |
|
okay, you are right i think. if i don't want to upgrade, i simply keep
using the 1.0 plugins and plugin client.
|
|
Yup. We might even support both in HttplugBundle? |
|
i'd rather not add that overhead in the bundle. can you add the versionadded blocks and then we merge this? |
|
Yep, working on it, also adding deprecation notice to plugins. It seems after all, that we might be able to have cross-compatibility between the new and the old client, plugins. PR coming. |
sagikazarmark
force-pushed
the
plugin_relocation
branch
from
63ca6be to
ac1cb80
Compare
|
Done. Can you check @dbu? |
sagikazarmark
force-pushed
the
plugin_relocation
branch
from
ac1cb80 to
7fcd80c
Compare
|
|
||
| .. versionadded:: 1.1 | ||
| The plugins were moved to the clients-common package in version 1.1. | ||
| If you work with version 1.0, you need to require the separate `php-http/plugins` package. |
There was a problem hiding this comment.
If you work with version 1.0, the interface is called Http\Client\Plugin\Plugin and you need to require the separate...
sagikazarmark
force-pushed
the
plugin_relocation
branch
from
7fcd80c to
9a867f8
Compare
|
Done |
|
👍 |
No description provided.