Add branch protection (#520)

* Added branch protection

* Updated method comments

Author: ampersand

lib/Github/Api/Repo.php

@@ -9,6 +9,7 @@
 use Github\Api\Repository\DeployKeys;
 use Github\Api\Repository\Downloads;
 use Github\Api\Repository\Projects;
+use Github\Api\Repository\Protection;
 use Github\Api\Repository\Releases;
 use Github\Api\Repository\Forks;
 use Github\Api\Repository\Hooks;
@@ -413,6 +414,18 @@ public function branches($username, $repository, $branch = null)
         return $this->get($url);
     }
 
+    /**
+     * Manage the protection of a repository branch.
+     *
+     * @link https://developer.github.com/v3/repos/branches/#get-branch-protection
+     *
+     * @return Protection
+     */
+    public function protection()
+    {
+        return new Protection($this->client);
+    }
+
     /**
      * Get the contributors of a repository.
      *

lib/Github/Api/Repository/Protection.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Github\Api\Repository;
+
+use Github\Api\AbstractApi;
+
+/**
+ * @link   https://developer.github.com/v3/repos/branches/
+ * @author Brandon Bloodgood <[email protected]>
+ */
+class Protection extends AbstractApi
+{
+    /**
+     * Retrieves configured protection for the provided branch
+     *
+     * @link https://developer.github.com/v3/repos/branches/#get-branch-protection
+     *
+     * @param  string $username   The user who owns the repository
+     * @param  string $repository The name of the repo
+     * @param  string $branch     The name of the branch
+     *
+     * @return array              The branch protection information
+     */
+    public function show($username, $repository, $branch)
+    {
+        return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/branches/'.rawurlencode($branch).'/protection');
+    }
+
+    /**
+     * Updates the repo's branch protection
+     *
+     * @link https://developer.github.com/v3/repos/branches/#update-branch-protection
+     *
+     * @param  string $username   The user who owns the repository
+     * @param  string $repository The name of the repo
+     * @param  string $branch     The name of the branch
+     * @param  array  $params     The branch protection information
+     *
+     * @return array              The updated branch protection information
+     */
+    public function update($username, $repository, $branch, array $params = array())
+    {
+        return $this->put('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/branches/'.rawurlencode($branch).'/protection', $params);
+    }
+}

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

@@ -0,0 +1,49 @@
+<?php
+
+namespace Github\Tests\Api\Repository;
+
+use Github\Tests\Api\TestCase;
+
+class ProtectionTest extends TestCase
+{
+    /**
+     * @test
+     */
+    public function shouldShowProtection()
+    {
+        $expectedValue = array('required_status_checks', 'required_pull_reqeust_reviews', 'restrictions');
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('get')
+            ->with('/repos/KnpLabs/php-github-api/branches/master/protection')
+            ->will($this->returnValue($expectedValue));
+
+        $this->assertEquals($expectedValue, $api->show('KnpLabs', 'php-github-api', 'master'));
+    }
+
+    /**
+     * @test
+     */
+    public function shouldUpdateProtection()
+    {
+        $expectedValue = array('required_status_checks', 'required_pull_reqeust_reviews', 'restrictions');
+        $data = array('required_status_checks' => null);
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('put')
+            ->with('/repos/KnpLabs/php-github-api/branches/master/protection', $data)
+            ->will($this->returnValue($expectedValue));
+
+        $this->assertEquals($expectedValue, $api->update('KnpLabs', 'php-github-api', 'master', $data));
+    }
+
+    /**
+     * @return string
+     */
+    protected function getApiClass()
+    {
+        return \Github\Api\Repository\Protection::class;
+    }
+}