Add ability to check that a file exists in repo branch/commit

lib/Github/Api/AbstractApi.php

@@ -12,6 +12,7 @@
  */
 abstract class AbstractApi implements ApiInterface
 {
+
     /**
      * The client
      *
@@ -27,6 +28,7 @@ abstract class AbstractApi implements ApiInterface
     protected $perPage;
 
     /**
+     *
      * @param Client $client
      */
     public function __construct(Client $client)
@@ -39,6 +41,7 @@ public function configure()
     }
 
     /**
+     *
      * @return null|int
      */
     public function getPerPage()
@@ -47,6 +50,7 @@ public function getPerPage()
     }
 
     /**
+     *
      * @param null|int $perPage
      */
     public function setPerPage($perPage)
@@ -77,6 +81,27 @@ protected function get($path, array $parameters = array(), $requestHeaders = arr
         return ResponseMediator::getContent($response);
     }
 
+    /**
+     * Send a HEAD request with query parameters
+     *
+     * @param string $path              Request path.
+     * @param array $parameters         HEAD parameters.
+     * @param array $requestHeaders     Request headers.
+     * @return \Guzzle\Http\Message\Response
+     */
+    protected function head($path, array $parameters = array(), $requestHeaders = array())
+    {
+        if (array_key_exists('ref', $parameters) && is_null($parameters['ref'])) {
+            unset($parameters['ref']);
+        }
+
+        $response = $this->client->getHttpClient()->request($path, null, 'HEAD', $requestHeaders, array(
+            'query' => $parameters
+        ));
+
+        return $response;
+    }
+
     /**
      * Send a POST request with JSON-encoded parameters.
      *
@@ -112,7 +137,6 @@ protected function postRaw($path, $body, $requestHeaders = array())
         return ResponseMediator::getContent($response);
     }
 
-
     /**
      * Send a PATCH request with JSON-encoded parameters.
      *
@@ -131,7 +155,6 @@ protected function patch($path, array $parameters = array(), $requestHeaders = a
         return ResponseMediator::getContent($response);
     }
 
-
     /**
      * Send a PUT request with JSON-encoded parameters.
      *
@@ -150,7 +173,6 @@ protected function put($path, array $parameters = array(), $requestHeaders = arr
         return ResponseMediator::getContent($response);
     }
 
-
     /**
      * Send a DELETE request with JSON-encoded parameters.
      *
@@ -172,7 +194,7 @@ protected function delete($path, array $parameters = array(), $requestHeaders =
     /**
      * Create a JSON encoded version of an array of parameters.
      *
-     * @param array $parameters   Request parameters
+     * @param array $parameters         Request parameters
      * @return null|string
      */
     protected function createJsonBody(array $parameters)

lib/Github/Api/Repository/Contents.php

@@ -6,6 +6,7 @@
 use Github\Exception\InvalidArgumentException;
 use Github\Exception\ErrorException;
 use Github\Exception\MissingArgumentException;
+use Github\Exception\TwoFactorAuthenticationRequiredException;
 
 /**
  * @link   http://developer.github.com/v3/repos/contents/
@@ -92,6 +93,42 @@ public function create($username, $repository, $path, $content, $message, $branc
         return $this->put($url, $parameters);
     }
 
+    /**
+     * Checks that a given path exists in a repository.
+     *
+     * @param string      $username the user who owns the repository
+     * @param string      $repository the name of the repository
+     * @param string      $path path of file to check
+     * @param null|string $reference reference to a branch or commit
+     * @return boolean
+     */
+    public function exists($username, $repository, $path, $reference = null)
+    {
+        $url = 'repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/contents';
+
+        if (null !== $path) {
+            $url .= '/'.rawurlencode($path);
+        }
+
+        try {
+            $response = $this->head($url, array(
+                'ref' => $reference
+            ));
+
+            if ($response->getStatusCode() != 200) {
+                return false;
+            }
+        }
+        catch (TwoFactorAuthenticationRequiredException $ex) {
+            throw $ex;
+        }
+        catch (\Exception $ex) {
+            return false;
+        }
+
+        return true;
+    }
+
     /**
      * Updates the contents of a file in a repository
      * @link http://developer.github.com/v3/repos/contents/#update-a-file

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

@@ -3,6 +3,7 @@
 namespace Github\Tests\Api\Repository;
 
 use Github\Tests\Api\TestCase;
+use Github\Exception\TwoFactorAuthenticationRequiredException;
 
 class ContentsTest extends TestCase
 {
@@ -38,6 +39,83 @@ public function shouldShowReadme()
         $this->assertEquals($expectedValue, $api->readme('KnpLabs', 'php-github-api'));
     }
 
+    /**
+     * @test
+     */
+    public function shouldReturnTrueWhenFileExists()
+    {
+        $responseMock = $this->getMockBuilder('\Guzzle\Http\Message\Response')
+            ->disableOriginalConstructor()
+            ->getMock();
+
+        $responseMock->expects($this->any())
+            ->method('getStatusCode')
+            ->willReturn(200);
+
+        $api = $this->getApiMock();
+            $api->expects($this->once())
+            ->method('head')
+            ->with('repos/KnpLabs/php-github-api/contents/composer.json', array('ref' => null))
+            ->will($this->returnValue($responseMock));
+
+        $this->assertEquals(true, $api->exists('KnpLabs', 'php-github-api', 'composer.json'));
+    }
+
+    private function getGuzzleResponseMock()
+    {
+        $responseMock = $this->getMockBuilder('\Guzzle\Http\Message\Response')
+            ->disableOriginalConstructor()
+            ->getMock();
+
+        return $responseMock;
+    }
+
+    public function getFailureStubsForExistsTest()
+    {
+        $nonOkResponseMock =$this->getGuzzleResponseMock();
+
+        $nonOkResponseMock->expects($this->any())
+            ->method('getStatusCode')
+            ->willReturn(403);
+
+        return array(
+            array($this->throwException(new \ErrorException())),
+            array($this->returnValue($nonOkResponseMock))
+        );
+    }
+
+    /**
+     * @test
+     * @dataProvider getFailureStubsForExistsTest
+     */
+    public function shouldReturnFalseWhenFileIsNotFound(\PHPUnit_Framework_MockObject_Stub $failureStub)
+    {
+        $expectedValue = array('some-header' => 'value');
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('head')
+            ->with('repos/KnpLabs/php-github-api/contents/composer.json', array('ref' => null))
+            ->will($failureStub);
+
+        $this->assertFalse($api->exists('KnpLabs', 'php-github-api', 'composer.json'));
+    }
+
+    /**
+     * @test
+     * @expectedException \Github\Exception\TwoFactorAuthenticationRequiredException
+     */
+    public function shouldBubbleTwoFactorAuthenticationRequiredExceptionsWhenCheckingFileRequiringAuth()
+    {
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('head')
+            ->with('repos/KnpLabs/php-github-api/contents/composer.json', array('ref' => null))
+            ->will($this->throwException(new TwoFactorAuthenticationRequiredException(0)));
+
+        $api->exists('KnpLabs', 'php-github-api', 'composer.json');
+    }
+
     /**
      * @test
      */

test/Github/Tests/Api/TestCase.php

@@ -19,7 +19,7 @@ protected function getApiMock()
         $client->setHttpClient($mock);
 
         return $this->getMockBuilder($this->getApiClass())
-            ->setMethods(array('get', 'post', 'postRaw', 'patch', 'delete', 'put'))
+            ->setMethods(array('get', 'post', 'postRaw', 'patch', 'delete', 'put', 'head'))
             ->setConstructorArgs(array($client))
             ->getMock();
     }