diff --git a/doc/gitdata/references.md b/doc/gitdata/references.md index cc4ee25eb7c..8cc2b971e7e 100644 --- a/doc/gitdata/references.md +++ b/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'); -``` \ No newline at end of file +``` diff --git a/lib/Github/Api/GitData/References.php b/lib/Github/Api/GitData/References.php index c54c0c8aad0..d67cbe512b9 100644 --- a/lib/Github/Api/GitData/References.php +++ b/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. * diff --git a/test/Github/Tests/Api/GitData/ReferencesTest.php b/test/Github/Tests/Api/GitData/ReferencesTest.php index 768085f69bf..70f17cde1d8 100644 --- a/test/Github/Tests/Api/GitData/ReferencesTest.php +++ b/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 */