[DOCS] OAuth1 3-legged example

Added example on how to use this library in combination with a 3rd party
OAuth1 client in a 3-legged flow.

Ref: #33

Author: vimishor

docs/examples/authentication.md

@@ -23,10 +23,11 @@ To use basic authentication, you need to attach `BasicAuthListener` to http clie
   $response = $user->get();
   ```
 
-### OAuth authorization
+### OAuth1 authorization
 This library comes with a `OAuthListener` which will sign all requests for you. All you need to do is to attach the listener to
 http client with oauth credentials before making a request.
 
+#### OAuth1 1-legged
   ```php
   // OAuth 1-legged example
   // You can create a new consumer at: https://bitbucket.org/account/user/<username or team>/api
@@ -44,6 +45,99 @@ http client with oauth credentials before making a request.
   $response = $user->get();
   ```
 
+#### OAuth1 3-legged
+
+You can use any 3rd party library to complete this [flow][3] and set OAuth credentials when you instantiate `OAuthListener`.
+
+In the following example [PHP League's OAuth 1.0 Client][4] is used.
+
+  ```php
+  session_start();
+
+  // @see: https://bitbucket.org/account/user/<username>/api
+  $oauth_params = array(
+      'identifier'    => 'aaa',
+      'secret'        => 'bbb',
+      'callback_uri'  => 'http://example.com/oauth1_3legged.php'
+  );
+
+  $server = new League\OAuth1\Client\Server\Bitbucket($oauth_params);
+
+  if (array_key_exists('profile', $_GET)) {
+      if (false === array_key_exists('bb_credentials', $_SESSION)) {
+          header('Location: ' . $oauth_params['callback_uri']);
+          exit;
+      }
+
+      $oauth_params = array_merge(unserialize($_SESSION['bb_credentials']), array(
+          'oauth_consumer_key'        => $oauth_params['identifier'],
+          'oauth_consumer_secret'     => $oauth_params['secret'],
+          'oauth_callback'            => $oauth_params['callback_uri'],
+      ));
+
+
+      $bitbucket = new \Bitbucket\API\Api();
+      $bitbucket->getClient()->addListener(
+          new \Bitbucket\API\Http\Listener\OAuthListener($oauth_params)
+      );
+
+      /** @var \Bitbucket\API\User $user */
+      $user = $bitbucket->api('User');
+
+      $profile = json_decode($user->get()->getContent(), true);
+      echo sprintf('<a href="?logout">Logout %s</a>', $profile['user']['username']);
+
+      // show all user repositories
+      echo '<h3>My repositories:</h3><ul>';
+      array_walk($profile['repositories'], function($repository) {
+          $repositoryUrl = str_replace('/1.0/repositories/', '', $repository['resource_uri']);
+          echo sprintf(
+              '<li><a href="http://bitbucket.org/%s">%s</a></li>', $repositoryUrl, $repository['name']
+          );
+      });
+      echo '</ul>';
+      exit;
+  } elseif (array_key_exists('login', $_GET)) {
+      // Retrieve temporary credentials
+      $temporaryCredentials = $server->getTemporaryCredentials();
+
+      // Store credentials in the session, we'll need them later
+      $_SESSION['temporary_credentials'] = serialize($temporaryCredentials);
+      session_write_close();
+
+      // Second part of OAuth 1.0 authentication is to redirect the
+      // resource owner to the login screen on the server.
+      $server->authorize($temporaryCredentials);
+      exit;
+  } elseif (array_key_exists('oauth_token', $_GET) && array_key_exists('oauth_verifier', $_GET)) {
+      // Retrieve the temporary credentials we saved before
+      $temporaryCredentials = unserialize($_SESSION['temporary_credentials']);
+
+      // We will now retrieve token credentials from the server
+      $tokenCredentials = $server->getTokenCredentials(
+          $temporaryCredentials, $_GET['oauth_token'], $_GET['oauth_verifier']
+      );
+
+      $oauth_params = array(
+          'oauth_token'               => $tokenCredentials->getIdentifier(),
+          'oauth_token_secret'        => $tokenCredentials->getSecret()
+      );
+
+      unset($_SESSION['temporary_credentials'], $_SESSION['token_credentials']);
+      $_SESSION['bb_credentials'] = serialize($oauth_params);
+      session_write_close();
+
+      // redirect the user to the profile page, in order to fetch his/her information.
+      header('Location: '.$oauth_params['callback_uri'].'?profile');
+      exit;
+  } elseif (array_key_exists('logout', $_GET)) {
+      unset($_SESSION['bb_credentials']);
+      session_write_close();
+  }
+
+  echo '<a href="?login">Login with BitBucket!</a>';
+  ```
+
 ### OAuth2 authorization
 
 You can use `OAuth2Listener` in order to make authorized requests using version 2 of OAuth protocol.
@@ -121,3 +215,4 @@ In the following example [PHP League's OAuth 2.0 Client][1] is used with [Bitbuc
 [1]: http://oauth2-client.thephpleague.com/
 [2]: https://github.com/stevenmaguire/oauth2-bitbucket
 [3]: http://oauthbible.com/#oauth-2-three-legged
+[4]: https://github.com/thephpleague/oauth1-client