Improve authentication documentation

Author: sagikazarmark

docs/components/authentication.md

@@ -15,6 +15,29 @@ $ composer require php-http/message
 
 ## Authentication methods
 
+Method           | Parameters                                        | Behavior
+---------------- | ------------------------------------------------- | --------
+[Basic Auth][1]  | Username and password                             | `Authorization` header of the HTTP specification
+Bearer           | Token                                             | `Authorization` header of the HTTP specification
+[WSSE][2]        | Username and password                             | `Authorization` header of the HTTP specification
+Query Params     | Array of param-value pairs                        | URI parameters
+Chain            | Array of authentication instances                 | Behaviors of the underlying authentication methods
+Matching         | An authentication instance and a matcher callback | Behavior of the underlying authentication method if the matcher callback passes
+
+[1]: https://en.wikipedia.org/wiki/Basic_access_authentication
+[2]: http://www.xml.com/pub/a/2003/12/17/dive.html
+
+
+## Integration with HTTPlug
+
+Normally requests must be authenticated "by hand" which is not really convenient.
+
+If you use HTTPlug, you can integrate this component into the client using the
+[authentication plugin](/httplug/plugins/authentication).
+
+
+## Examples
+
 General usage looks like the following:
 
 ``` php
@@ -27,38 +50,51 @@ $authentication->authenticate($request);
 
 ### Basic Auth
 
-This authentication method accepts two parameters: username and password. Getters/Setters are provided by
-`Http\Message\Authentication\UserPasswordPair` trait.
-
 ``` php
 use Http\Message\Authentication\BasicAuth;
 
 $authentication = new BasicAuth('username', 'password');
-
-// These details can be set later as well
-// There are also getters with the appropriate method names
-$authentication->setUsername('username');
-$authentication->setPassword('password');
 ```
 
 
 ### Bearer
 
-This authentication method accepts one parameter: a token.
-
 ``` php
 use Http\Message\Authentication\Bearer;
 
 $authentication = new Bearer('token');
+```
+
+
+### WSSE
+
+``` php
+use Http\Message\Authentication\Wsse;
 
-// Token can be set later as well
-$authentication->setToken('token');
+$authentication = new Wsse('username', 'password');
 ```
 
 
-### Chain
+### Query Params
+
+`http://api.example.com/endpoint?access_token=9zh987g86fg87gh978hg9g79`
+
+
+``` php
+use Http\Authentication\QueryParams;
+
+$authentication = new QueryParams([
+    'access_token' => '9zh987g86fg87gh978hg9g79',
+]);
+```
+
+!!! danger "Warning:"
+    Using query parameters for authentication is not safe.
+    Only use it when this is the only authentication method offered by a third party application.
 
-This authentication method accepts one parameter: an array of other authentication methods.
+
+
+### Chain
 
 The idea behind this authentication method is that in some cases you might need to
 authenticate the request with multiple methods.
@@ -76,17 +112,6 @@ $authenticationChain = [
 ];
 
 $authentication = new Chain($authenticationChain);
-
-// Authentication chain can be modified later
-$authenticationChain = $authentication->getAuthenticationChain();
-
-array_pop($authenticationChain);
-
-$authentication->setAuthenticationChain($authenticationChain);
-
-$authentication->clearAuthenticationChain();
-
-$authentication->addAuthentication(new AuthenticationMethod3());
 ```
 
 
@@ -102,60 +127,31 @@ For example a common use case is to authenticate requests sent to certain paths.
 
 
 ``` php
-use Http\Message\Authentication\Mathing;
+use Http\Message\Authentication\Matching;
+use Psr\Http\Message\RequestInterface;
 
-$authentication = new Mathing(new AuthenticationMethod1(), function () { return true; });
+$authentication = new Matching(
+    new AuthenticationMethod1(),
+    function (RequestInterface $request) {
+        $path = $request->getUri()->getPath();
 
-// There are also getters with the appropriate method names
-$authentication->setAuthentication(new AuthenticationMethod2());
-$authentication->setMatcher(function () { return false; });
+        return 0 === strpos($path, '/api');
+    }
+);
 ```
 
 
-In order to ease creating matchers for URLs/paths, there is a static factory method for this purpose.
+In order to ease creating matchers for URLs/paths, there is a static factory method for this purpose: `createUrlMatcher`
 The first argument is an authentication method, the second is a regexp to match against the URL.
 
 
 ``` php
-use Http\Message\Authentication\Mathing;
+use Http\Message\Authentication\Matching;
 
 $authentication = Matching::createUrlMatcher(new AuthenticationMethod(), '\/api');
 ```
 
 
-### Query Params
-
-Add authentication details as URL Query params:
-
-`http://api.example.com/endpoint?access_token=9zh987g86fg87gh978hg9g79`
-
-
-``` php
-use Http\Authentication\QueryParams;
-
-$authentication = new QueryParams([
-    'access_token' => '9zh987g86fg87gh978hg9g79',
-]);
-```
-
-!!! danger "Warning:"
-    Using query parameters for authentication is not safe.
-    Only use it when absolutely necessary.
-
-
-### WSSE
-
-This method implements [WSSE Authentication](http://www.xml.com/pub/a/2003/12/17/dive.html).
-Just like Basic Auth, it also accepts a username-password pair and exposes the same methods as well.
-
-
-``` php
-use Http\Message\Authentication\Wsse;
-
-$authentication = new Wsse('username', 'password');
-```
-
-
 ## Implement your own
 
 Implementing an authentication method is easy: only one method needs to be implemented.
@@ -170,16 +166,8 @@ class MyAuth implements Authentication
     {
         // do something with the request
 
-        // keep in mind that the request is immutable!
+        // keep in mind that the request is immutable - return the updated version of the request with the authentication information added to it.
         return $request;
     }
 }
 ```
-
-
-## Integration with HTTPlug
-
-Normally requests must be authenticated "by hand" which is not really convenient.
-
-If you use HTTPlug, you can integrate this component into the client using the
-[authentication plugin](/httplug/plugins/authentication).

docs/httplug/plugins/authentication.md

@@ -1,6 +1,6 @@
 # Authentication Plugin
 
-This plugin uses the [authentication component](/components/authentication) to authenticate all requests sent through
+This plugin uses the [authentication component](/components/authentication) to authenticate requests sent through
 the client.
 
 
@@ -13,4 +13,5 @@ use Http\Plugins\AuthenticationPlugin;
 $pluginClient = new PluginClient(new HttpClient(), [new AuthenticationPlugin(new AuthenticationMethod()]);
 ```
 
-Check the [component documentation](/components/authentication) for the list of available authentication methods.
+Check the [authentication component documentation](/components/authentication)
+for the list of available authentication methods.