Add collaborator permission call (KnpLabs#678)

* Add collaborator permission call

* Add docs for permission() call

Author: selator

doc/repos.md

@@ -27,7 +27,6 @@ $repos = $client->api('repo')->find('symfony');
 ```
 
 Returns a list of repositories.
-
 #### Advanced search
 
 You can filter the results by language. It takes the same values as the language drop down on [http://github.com/search](http://github.com/search).
@@ -179,20 +178,29 @@ Returns a list of the collaborators for the 'reponame' repository.
 ### Add a collaborator to a repository
 
 ```php
-$client->api('repo')->collaborators()->add('username', 'reponame', 'KnpLabs');
+$client->api('repo')->collaborators()->add('username', 'reponame', 'collaborator');
 ```
 
-Adds the 'username' user as collaborator to the 'reponame' repository.
+Adds the 'collaborator' user as collaborator to the 'reponame' repository.
 
 ### Remove a collaborator from a repository
 
 > Requires [authentication](security.md).
 
 ```php
-$client->api('repo')->collaborators()->remove('username', 'reponame', 'KnpLabs');
+$client->api('repo')->collaborators()->remove('username', 'reponame', 'collaborator');
 ```
 
-Remove the 'username' collaborator from the 'reponame' repository.
+Remove the 'collaborator' collaborator from the 'reponame' repository.
+
+### Get the permissions of a collaborator for a repository
+
+```php
+$permissions = $client->api('repo')->collaborators()->permission('username', 'reponame', 'collaborator');
+```
+
+Returns the permissions of 'collaborator' collaborator for the 'reponame' repository.
+
 
 ### Watch and unwatch a repository
 

lib/Github/Api/Repository/Collaborators.php

@@ -67,4 +67,16 @@ public function remove($username, $repository, $collaborator)
     {
         return $this->delete('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/collaborators/'.rawurlencode($collaborator));
     }
+
+    /**
+     * @link https://developer.github.com/v3/repos/collaborators/#review-a-users-permission-level
+     * @param $username
+     * @param $repository
+     * @param $collaborator
+     * @return array|string
+     */
+    public function permission($username, $repository, $collaborator)
+    {
+        return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/collaborators/'.rawurlencode($collaborator).'/permission');
+    }
 }

test/Github/Tests/Api/Repository/CollaboratorsTest.php

@@ -70,6 +70,22 @@ public function shouldRemoveRepositoryCollaborator()
         $this->assertEquals($expectedValue, $api->remove('KnpLabs', 'php-github-api', 'l3l0'));
     }
 
+    /**
+     * @test
+     */
+    public function shouldGetRepositoryCollaboratorPermission()
+    {
+        $expectedValue = array(array('permission' => 'admin', 'user' => 'l3l0'));
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('get')
+            ->with('/repos/KnpLabs/php-github-api/collaborators/l3l0/permission')
+            ->will($this->returnValue($expectedValue));
+
+        $this->assertEquals($expectedValue, $api->permission('KnpLabs', 'php-github-api', 'l3l0'));
+    }
+
     /**
      * @return string
      */