feature #875 Add Support For GitData Reference Matching Methods (nickpoulos)

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

Discussion
----------

This PR adds two methods - `matchingBranch()` and `matchingTag()` to `GitHub/Api/GitData/References.php`.  These methods return the references for a given branch or tag, respectively.  

There are two more tests to `GitHub/Tests/Api/GitData/ReferencesTest.php`, `shouldGetAllMatchingBranchRepoReferences` and `shouldGetAllMatchingTagRepoReferences`.

Documentation here: https://developer.github.com/v3/git/refs/#list-matching-references


Commits
-------

fe50ad1 Add matchingBranch() and matchingTags() Methods To References.php
791f563 Add New Tests In ReferencesTest For Our Two New Methods
f9f39af Apply Requested Fixes
8107e13 Add Documentation For method matching() in gitdata/references.md
7e5dfc9 Refactor Dual Methods To Single, and Fix Test
61fe18b Remove link from DocBlock
2856710 Add $this->encodeReference() call Inside matching()
1fc9471 Update ReferencesTest.php To Use A More Realistic Parameter
d63d9a1 StyleCI Add Period

Author: nickpoulos

doc/gitdata/references.md

@@ -7,6 +7,11 @@
 $references = $client->api('gitData')->references()->all('KnpLabs', 'php-github-api');
 ```
 
+### List Matching references
+```php
+$references = $client->api('gitData')->references()->matching('KnpLabs', 'php-github-api', 'heads/branchName'); // use 'tags/tagName' for third argument if ref is tag
+```
+
 ### Show a reference
 
 ```php
@@ -41,4 +46,4 @@ $references = $client->api('gitData')->references()->branches('KnpLabs', 'php-gi
 ### List all tags
 ```php
 $references = $client->api('gitData')->references()->tags('KnpLabs', 'php-github-api');
-```
+```

lib/Github/Api/GitData/References.php

@@ -25,6 +25,22 @@ public function all($username, $repository)
         return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/refs');
     }
 
+    /**
+     * Get all matching references for the supplied reference name.
+     *
+     * @param string $username
+     * @param string $repository
+     * @param string $reference
+     *
+     * @return array
+     */
+    public function matching(string $username, string $repository, string $reference): array
+    {
+        $reference = $this->encodeReference($reference);
+
+        return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/git/matching-refs/'.$reference);
+    }
+
     /**
      * Get all branches of a repository.
      *

test/Github/Tests/Api/GitData/ReferencesTest.php

@@ -71,6 +71,22 @@ public function shouldGetAllRepoReferences()
         $this->assertEquals($expectedValue, $api->all('l3l0', 'l3l0repo'));
     }
 
+    /**
+     * @test
+     */
+    public function shouldGetAllMatchingReferences()
+    {
+        $expectedValue = [['reference' => 'some data']];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('get')
+            ->with('/repos/l3l0/l3l0repo/git/matching-refs/heads/refName')
+            ->will($this->returnValue($expectedValue));
+
+        $this->assertEquals($expectedValue, $api->matching('l3l0', 'l3l0repo', 'heads/refName'));
+    }
+
     /**
      * @test
      */