Merge branch 'feature/api-v2' into develop

- Updated Repositories/Repository to API 2.0 (+BC).

Methods that uses API 1.0 endpoints and have a corespondent in API 2.0 (like, but not limited to: Repository::create) have been deprecated.

Author: vimishor

docs/Home.md

@@ -18,7 +18,7 @@ A simple PHP wrapper for Bitbucket API.
     * [Issues](repositories/issues.md)
     * [Links](repositories/links.md)
     * [PullRequests](repositories/pullrequests.md) (API 2.0)
-    * [Repository](repositories/repository.md)
+    * [Repository](repositories/repository.md) (API 2.0)
     * [Services](repositories/services.md)
     * [Src](repositories/src.md)
     * [Wiki](repositories/wiki.md)

docs/repositories/pullrequests.md

@@ -9,17 +9,17 @@ $pull = new Bitbucket\API\Repositories\PullRequests();
 $pull->setCredentials( new Bitbucket\API\Authentication\Basic($bb_user, $bb_pass) );
 ```
 
-### Get all pull requests:
+### Get all pull requests: (API 2.0)
 ```php
 $pull->all($account_name, $repo_slug);
 ```
 
-### Get all merged pull requests:
+### Get all merged pull requests: (API 2.0)
 ```php
 $pull->all($account_name, $repo_slug, array('state' => 'merged'));
 ```
 
-### Create a new pull request:
+### Create a new pull request: (API 2.0)
 ```php
 $pull->create('gentle', 'secret-repo', array(
     'title'         => 'Test PR',
@@ -40,7 +40,7 @@ $pull->create('gentle', 'secret-repo', array(
 ));
 ```
 
-### Update a pull request:
+### Update a pull request: (API 2.0)
 ```php
 $pull->update('gentle', 'secret-repo', 1, array(
     'title'         => 'Test PR (updated)',
@@ -52,46 +52,46 @@ $pull->update('gentle', 'secret-repo', 1, array(
 ));
 ```
 
-### Get a specific pull request:
+### Get a specific pull request: (API 2.0)
 ```php
 $pull->get($account_name, $repo_slug, 1);
 ```
 
-### Get the commits for a pull request:
+### Get the commits for a pull request: (API 2.0)
 ```php
 $pull->commits($account_name, $repo_slug, 1);
 ```
 
-### Approve a pull request:
+### Approve a pull request: (API 2.0)
 ```php
 $pull->approve($account_name, $repo_slug, 1);
 ```
 
-### Delete a a pull request approval:
+### Delete a a pull request approval: (API 2.0)
 ```php
 $pull->delete($account_name, $repo_slug, 1);
 ```
 
-### Get the diff for a pull request:
+### Get the diff for a pull request: (API 2.0)
 ```php
 $pull->diff($account_name, $repo_slug, 1);
 ```
 
-### Get the log of a pull request activity
+### Get the log of a pull request activity: (API 2.0)
 If pull request ID is omitted, the entire repository's pull request activity is returned.
 
 ```php
 $pull->activity($account_name, $repo_slug, 1);
 ```
 
-### Accept and merge a pull request:
+### Accept and merge a pull request: (API 2.0)
 ```php
 $pull->accept($account_name, $repo_slug, 1, array(
     'message' => 'This message will be used for merge commit.'
 ));
 ```
 
-### Decline a pull request:
+### Decline a pull request: (API 2.0)
 ```php
 $pull->accept($account_name, $repo_slug, 1, array(
     'message' => 'Please update the docs to reflect new changes.'

docs/repositories/repository.md

@@ -9,7 +9,14 @@ $repo = new Bitbucket\API\Repositories\Repository();
 $repo->setCredentials( new Bitbucket\API\Authentication\Basic($bb_user, $bb_pass) );
 ```
 
-### Create a new repository:
+### Get information associated with an individual repository: (API 2.0)
+```php
+$repo->get($account_name, $repo_slug);
+```
+
+### Create a new repository: (API 1.0)
+**NOTE:** API 1.0 endpoint for repository creation has been deprecated, so please use the new API 2.0 endpoint described bellow.
+
 ```php
 $repo->create($repo_slug, array(
     'description'   => 'My super secret project.',
@@ -18,6 +25,17 @@ $repo->create($repo_slug, array(
 ));
 ```
 
+### Create a new repository: (API 2.0)
+```php
+$repo->create($account_name, $repo_slug, array(
+    'scm'               => 'git',
+    'description'       => 'My super secret project.',
+    'language'          => 'php',
+    'is_private'        => true,
+    'forking_policy'    => 'no_public_forks',
+));
+```
+
 ### Update an existing repository:
 ```php
 $repo->update($account_name, $repo_slug, array(
@@ -27,11 +45,21 @@ $repo->update($account_name, $repo_slug, array(
 ));
 ```
 
-### Delete a repository:
+### Delete a repository: (API 2.0)
 ```php
 $repo->delete($account_name, $repo_slug);
 ```
 
+### Get the list of accounts watching a repository: (API 2.0)
+```php
+$repo->watchers($account_name, $repo_slug);
+```
+
+### Get the list of repository forks: (API 2.0)
+```php
+$repo->forks($account_name, $repo_slug);
+```
+
 ### Fork a repository:
 ```php
 $repo->fork($account_name, $repo_slug, $fork_slug, array(

lib/Bitbucket/API/Repositories/Repository.php

@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * This file is part of the bitbucket-api package.
  *
  * (c) Alexandru G. <alex@gentle.ro>
@@ -12,16 +12,73 @@
 namespace Bitbucket\API\Repositories;
 
 use Bitbucket\API;
+use Buzz\Message\MessageInterface;
 
 /**
- * Repository class
- *
  * Allows you to create a new repository or edit a specific one.
  *
  * @author  Alexandru G.    <alex@gentle.ro>
  */
 class Repository extends API\Api
 {
+    /**
+     * Get information associated with an individual repository.
+     *
+     * @access public
+     * @param  string           $account The team or individual account owning the repository.
+     * @param  string           $repo    The repository identifier.
+     * @return MessageInterface
+     */
+    public function get($account, $repo)
+    {
+        return $this->getClient()->setApiVersion('2.0')->get(
+            sprintf('repositories/%s/%s', $account, $repo)
+        );
+    }
+
+    /**
+     * Create a new repository
+     *
+     * If `$params` are omitted, a private git repository will be created,
+     * with a "no forking" policy.
+     *
+     * @access public
+     * @param  string           $account The team or individual account owning the repository.
+     * @param  string           $repo    The repository identifier.
+     * @param  array            $params  Additional parameters
+     * @return MessageInterface
+     *
+     * @see https://confluence.atlassian.com/x/WwZAGQ
+     */
+    public function create($account, $repo, $params = array())
+    {
+        // Keep BC for now.
+        // @todo[1]: to be removed.
+        if (is_array($repo)) {
+            return $this->createLegacy($account, $repo);
+        }
+
+        // allow developer to directly specify params as json if (s)he wants.
+        if (!empty($params) && is_array($params)) {
+            $params = json_encode(array_merge(
+                array(
+                    'scm'               => 'git',
+                    'name'              => $repo,
+                    'is_private'        => true,
+                    'description'       => 'My secret repo',
+                    'forking_policy'    => 'no_forks',
+                ),
+                $params
+            ));
+        }
+
+        return $this->getClient()->setApiVersion('2.0')->post(
+            sprintf('repositories/%s/%s', $account, $repo),
+            $params,
+            array('Content-Type' => 'application/json')
+        );
+    }
+
     /**
      * Create a new repository
      *
@@ -38,8 +95,11 @@ class Repository extends API\Api
      * @param  string $name   The name of the repository
      * @param  array  $params Additional parameters
      * @return mixed
+     *
+     * @deprecated This API 1.0 endpoint is deprecated.
+     * @see $this->create() Sintax for using API 2.0 endpoint
      */
-    public function create($name, array $params = array())
+    private function createLegacy($name, array $params = array())
     {
         $params['name'] = $name;
 
@@ -58,7 +118,7 @@ public function create($name, array $params = array())
      * @param  array  $params  Additional parameters
      * @return mixed
      *
-     * @see https://confluence.atlassian.com/display/BITBUCKET/repository+Resource#repositoryResource-PUTarepositoryupdate
+     * @see https://confluence.atlassian.com/x/WwZAGQ
      */
     public function update($account, $repo, array $params = array())
     {
@@ -72,17 +132,47 @@ public function update($account, $repo, array $params = array())
      * Delete a repository
      *
      * @access public
-     * @param  string $account The team or individual account owning the repository.
-     * @param  string $repo    The repository identifier.
-     * @return mixed
+     * @param  string           $account The team or individual account owning the repository.
+     * @param  string           $repo    The repository identifier.
+     * @return MessageInterface
      */
     public function delete($account, $repo)
     {
-        return $this->requestDelete(
+        return $this->getClient()->setApiVersion('2.0')->delete(
             sprintf('repositories/%s/%s', $account, $repo)
         );
     }
 
+    /**
+     * Gets the list of accounts watching a repository.
+     *
+     * @access public
+     * @param  string           $account The team or individual account owning the repository.
+     * @param  string           $repo    The repository identifier.
+     * @return MessageInterface
+     */
+    public function watchers($account, $repo)
+    {
+        return $this->getClient()->setApiVersion('2.0')->get(
+            sprintf('repositories/%s/%s/watchers', $account, $repo)
+        );
+    }
+
+    /**
+     * Gets the list of repository forks.
+     *
+     * @access public
+     * @param  string           $account The team or individual account owning the repository.
+     * @param  string           $repo    The repository identifier.
+     * @return MessageInterface
+     */
+    public function forks($account, $repo)
+    {
+        return $this->getClient()->setApiVersion('2.0')->get(
+            sprintf('repositories/%s/%s/forks', $account, $repo)
+        );
+    }
+
     /**
      * Fork a repository
      *