Merge branch 'release/0.7.0'

.travis.yml

@@ -7,15 +7,21 @@ php:
   - hhvm
 
 matrix:
+  fast_finish: true
   allow_failures:
     - php: 5.3
 
 before_script:
-  - curl -s http://getcomposer.org/installer | php
-  - php composer.phar install --prefer-source
+  - travis_retry composer self-update
+  - composer --version
+  - travis_retry composer install --no-interaction --prefer-source
 
 script:
-  - mkdir -p build/logs
-  - php vendor/bin/phpunit
+  - mkdir -p ./build/logs
+  - php vendor/bin/phpunit --coverage-clover=./build/logs/coverage.clover
 
 after_script:
+  - travis_retry wget https://scrutinizer-ci.com/ocular.phar -O ocular.phar
+  - travis_retry php ocular.phar self-update
+  - php ocular.phar --version
+  - travis_retry php ocular.phar code-coverage:upload --repository=b/gentlero/bitbucket-api --format=php-clover ./build/logs/coverage.clover

CHANGELOG.md

@@ -2,7 +2,19 @@
 All notable changes to this project will be documented in this file.  
 This project adheres to [Semantic Versioning](http://semver.org/).
 
-## [Unreleased][unreleased]
+## [0.7.0] / 2015-09-08
+
+### Added:
+  - Implemented webhooks endpoints.
+  - Toggle spam on a changeset comment. (issue #2)
+  - Support for OAuth2. (issue #34)
+
+### Changed:
+  - Marked Repositories/Services as deprecated in favor of Repositories/Hooks. (issue #29)
+  - [DOCS] Added example on how to use this library in combination with a 3rd party OAuth1 client in a 3-legged flow.
+
+### Fixed:
+  - `forking_policy` parameter renamed to `fork_policy` on repository endpoint. (issue #32)
 
 ## 0.6.2 / 2015-05-18
 

README.md

@@ -2,9 +2,9 @@
 
 [![Latest Version](https://img.shields.io/packagist/v/gentle/bitbucket-api.svg?style=flat-square)](https://packagist.org/packages/gentle/bitbucket-api)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/gentlero/bitbucket-api/blob/master/LICENSE)
-[![Build Status](http://img.shields.io/travis/gentlero/bitbucket-api/master.svg?style=flat-square)](https://travis-ci.org/gentlero/bitbucket-api)
-[![Coverage Status](https://img.shields.io/scrutinizer/coverage/b/gentlero/bitbucket-api/master.svg?style=flat-square)](https://scrutinizer-ci.com/b/gentlero/bitbucket-api/?branch=master)
-[![Code quality](http://img.shields.io/scrutinizer/b/gentlero/bitbucket-api/master.svg?style=flat-square)](https://scrutinizer-ci.com/b/gentlero/bitbucket-api/?branch=master)
+[![Build Status](https://img.shields.io/travis/gentlero/bitbucket-api/master.svg?style=flat-square)](https://travis-ci.org/gentlero/bitbucket-api)
+[![Coverage Status](https://img.shields.io/scrutinizer/coverage/b/gentlero/bitbucket-api.svg?style=flat-square)](https://scrutinizer-ci.com/b/gentlero/bitbucket-api/?branch=develop)
+[![Code quality](https://img.shields.io/scrutinizer/b/gentlero/bitbucket-api.svg?style=flat-square)](https://scrutinizer-ci.com/b/gentlero/bitbucket-api/?branch=develop)
 
 Simple Bitbucket API wrapper for PHP >= 5.3.2.
 

composer.json

@@ -14,7 +14,7 @@
         }
     ],
     "require": {
-        "php":                  "~5.3",
+        "php":                  ">=5.3",
         "kriswallsmith/buzz":   "~0.13",
         "jacobkiers/oauth":     "~1.0.10"
     },
@@ -29,5 +29,8 @@
     },
     "autoload": {
         "psr-0": { "Bitbucket\\": "lib/" }
+    },
+    "scripts": {
+        "test": "vendor/bin/phpunit"
     }
 }

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,8 +45,174 @@ 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.
+
+#### OAuth2 client credentials (_2-legged flow_)
+
+  ```php
+  // @see: https://bitbucket.org/account/user/<username or team>/api
+  $oauth_params = array(
+      'client_id'         => 'aaa',
+      'client_secret'     => 'bbb'
+  );
+
+  $bitbucket = new \Bitbucket\API\Api();
+  $bitbucket->getClient()->addListener(
+      new \Bitbucket\API\Http\Listener\OAuth2Listener($oauth_params)
+  );
+
+  $repositories = $bitbucket->api('Repositories');
+  $response     = $repositories->all('my_account'); // should include private repositories
+  ```
+
+#### OAuth2 Authorization code (_3-legged flow_)
+
+You can use any 3rd party library to complete this [flow][3] and set `access_token` option when you instantiate `OAuth2Listener`.
+
+In the following example [PHP League's OAuth 2.0 Client][1] is used with [Bitbucket Provider][2].
+
+  ```php
+  session_start();
+
+  $provider = new Stevenmaguire\OAuth2\Client\Provider\Bitbucket([
+      'clientId'          => $_ENV['bitbucket_consumer_key'],
+      'clientSecret'      => $_ENV['bitbucket_consumer_secret'],
+      'redirectUri'       => 'http://example.com/bitbucket_login.php'
+  ]);
+  if (!isset($_GET['code'])) {
+
+      // If we don't have an authorization code then get one
+      $authUrl = $provider->getAuthorizationUrl();
+      $_SESSION['oauth2state'] = $provider->getState();
+      header('Location: '.$authUrl);
+      exit;
+
+  // Check given state against previously stored one to mitigate CSRF attack
+  } elseif (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['oauth2state'])) {
+
+      unset($_SESSION['oauth2state']);
+      exit('Invalid state');
+
+  } else {
+
+      // Try to get an access token (using the authorization code grant)
+      $token = $provider->getAccessToken('authorization_code', [
+          'code' => $_GET['code']
+      ]);
+
+      $bitbucket = new Bitbucket\API\Repositories();
+      $bitbucket->getClient()->addListener(
+          new \Bitbucket\API\Http\Listener\OAuth2Listener(
+              array('access_token'  => $token->getToken())
+          )
+      );
+
+      echo $bitbucket->all('my_account')->getContent(); // should include private repositories
+  }
+  ```
+
 ----
 
 #### Related:
   * [Authentication @ BB Wiki](https://confluence.atlassian.com/display/BITBUCKET/Use+the+Bitbucket+REST+APIs#UsetheBitbucketRESTAPIs-Authentication)
   * [OAuth on Bitbucket @ BB Wiki](https://confluence.atlassian.com/display/BITBUCKET/OAuth+on+Bitbucket)
+
+[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

docs/examples/index.md

@@ -46,7 +46,8 @@ title: Examples
     - [Pull requests](repositories/pull-requests.html)
       - [Comments](repositories/pull-requests/comments.html)
     - [Repository](repositories/repository.html)
-    - [Services](repositories/services.html)
+    - ~~[Services](repositories/services.html)~~ (deprecated since 0.7.0 -- @see [WebHooks](repositories/webhooks.html))
+    - [Hooks](repositories/webhooks.html)
     - [Src](repositories/src.html)
     - [Wiki](repositories/wiki.html)
   - [Teams](teams.html)

docs/examples/repositories/commits.md

@@ -11,7 +11,7 @@ Retrieve and compare information about commits.
 ### Prepare:
 
 ```php
-$commits = new Bitbucket\API\Repositories\PullRequests();
+$commits = new Bitbucket\API\Repositories\Commits();
 $commits->setCredentials( new Bitbucket\API\Authentication\Basic($bb_user, $bb_pass) );
 ```