feature #1075 Add the ability to download raw file, needed when size …

…> 1MB (genintho)

This PR was squashed before being merged into the 3.4.x-dev branch.

Discussion
----------

API DOC https://docs.github.com/en/rest/repos/contents

The API call to return the content of a file return an empty content if a file is bigger than 1MB. 
To be able to download that file, we need to provide the header `application/vnd.github.VERSION.raw`. 
When doing so, the API return a the raw file, instead of a JSON object with some attributes + the file content. 

Because the API has a different behavior, I preferred to create a dedicated method as opposed to provide accept more option in the download method and having a bunch of if/else.


Note: a 3rd behavior exists for that API call when downloading markdown and passing the `application/vnd.github.VERSION.html` header, which is not supported by this code change.

Commits
-------

520ffb9 Add the ability to download raw file, needed when size > 1MB
ff458a2 Restore modification committed by mistake
e7c393f Style fix

lib/Github/Api/Repository/Contents.php

@@ -61,14 +61,15 @@ public function readme($username, $repository, $reference = null)
      *
      * @link http://developer.github.com/v3/repos/contents/
      *
-     * @param string      $username   the user who owns the repository
-     * @param string      $repository the name of the repository
-     * @param string|null $path       path to file or directory
-     * @param string|null $reference  reference to a branch or commit
+     * @param string      $username       the user who owns the repository
+     * @param string      $repository     the name of the repository
+     * @param string|null $path           path to file or directory
+     * @param string|null $reference      reference to a branch or commit
+     * @param array       $requestHeaders request headers
      *
      * @return array|string information for file | information for each item in directory
      */
-    public function show($username, $repository, $path = null, $reference = null)
+    public function show($username, $repository, $path = null, $reference = null, $requestHeaders = [])
     {
         $url = '/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/contents';
         if (null !== $path) {
@@ -77,7 +78,7 @@ public function show($username, $repository, $path = null, $reference = null)
 
         return $this->get($url, [
             'ref' => $reference,
-        ]);
+        ], $requestHeaders);
     }
 
     /**
@@ -294,4 +295,25 @@ public function download($username, $repository, $path, $reference = null)
 
         return base64_decode($file['content']) ?: null;
     }
+
+    /**
+     * Get the raw content of a file in a repository.
+     *
+     * Use this method instead of the download method if your file is bigger than 1MB
+     *
+     * @see https://docs.github.com/en/rest/repos/contents
+     *
+     * @param string      $username   the user who owns the repository
+     * @param string      $repository the name of the repository
+     * @param string      $path       path to file
+     * @param string|null $reference  reference to a branch or commit
+     *
+     * @return array|string
+     */
+    public function rawDownload($username, $repository, $path, $reference = null)
+    {
+        return $this->show($username, $repository, $path, $reference, [
+            'Accept' => 'application/vnd.github.VERSION.raw',
+        ]);
+    }
 }

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

@@ -319,6 +319,23 @@ public function shouldDownloadForSpacedPath()
         $this->assertEquals($expectedValue, $api->download('mads379', 'scala.tmbundle', 'Syntaxes/Simple Build Tool.tmLanguage'));
     }
 
+    /**
+     * @test
+     */
+    public function shouldRawDownloadForGivenPath()
+    {
+        // The show() method return
+        $getValue = include __DIR__.'/fixtures/ContentsDownloadFixture.php';
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('get')
+            ->with('/repos/KnpLabs/php-github-api/contents/test%2FGithub%2FTests%2FApi%2FRepository%2FContentsTest.php', ['ref' => null])
+            ->will($this->returnValue($getValue));
+
+        $this->assertEquals($getValue, $api->rawDownload('KnpLabs', 'php-github-api', 'test/Github/Tests/Api/Repository/ContentsTest.php'));
+    }
+
     /**
      * @return string
      */