diff --git a/doc/search.md b/doc/search.md new file mode 100644 index 00000000000..85936170162 --- /dev/null +++ b/doc/search.md @@ -0,0 +1,48 @@ +## Search API +[Back to the navigation](index.md) + +Searching repositories, code, issues and users. +Wrap [GitHub Search API](http://developer.github.com/v3/search/). All methods are described on that page. + +### Search repositories + +```php +$repos = $client->api('search')->repositories('github language:php'); +``` + +Returns a list of repositories found by such criteria. + +### Search code + +```php +$repos = $client->api('search')->code('@todo language:php'); +``` + +Returns a list of files found by such criteria (containing "@todo" and language==php). + +### Search issues + +```php +$repos = $client->api('search')->issues('bug language:php'); +``` + +Returns a list of issues found by such criteria. + +### Search users + +```php +$repos = $client->api('search')->users('location:Amsterdam language:php'); +``` + +Returns a list of users found by such criteria. + +### Sorting results + +You can sort results using 2-3 arguments. + +```php +$repos = $client->api('repo')->repositories('...', 'created', 'asc'); +$repos = $client->api('repo')->code('...........', 'indexed', 'desc'); +$repos = $client->api('repo')->issues('.........', 'comments', 'asc'); +$repos = $client->api('repo')->users('..........', 'followers', 'asc'); +``` diff --git a/lib/Github/Api/Search.php b/lib/Github/Api/Search.php new file mode 100644 index 00000000000..bf7dab21ce7 --- /dev/null +++ b/lib/Github/Api/Search.php @@ -0,0 +1,80 @@ + + */ +class Search extends AbstractApi +{ + + /** + * Search repositories by filter (q) + * @link https://developer.github.com/v3/search/#search-repositories + * + * @param string $q the filter + * @param string $sort the sort field + * @param string $order asc/desc + * + * @return array list of repositories found + */ + public function repositories($q, $sort = 'updated', $order = 'desc') + { + return $this->get('/search/repositories', array('q' => $q, 'sort' => $sort, 'order' => $order)); + } + + /** + * Search issues by filter (q) + * @link https://developer.github.com/v3/search/#search-issues + * + * @param string $q the filter + * @param string $sort the sort field + * @param string $order asc/desc + * + * @return array list of issues found + */ + public function issues($q, $sort = 'updated', $order = 'desc') + { + return $this->get('/search/issues', array('q' => $q, 'sort' => $sort, 'order' => $order)); + } + + /** + * Search code by filter (q) + * @link https://developer.github.com/v3/search/#search-code + * + * @param string $q the filter + * @param string $sort the sort field + * @param string $order asc/desc + * + * @return array list of code found + */ + public function code($q, $sort = 'updated', $order = 'desc') + { + return $this->get('/search/code', array('q' => $q, 'sort' => $sort, 'order' => $order)); + } + + /** + * Search users by filter (q) + * @link https://developer.github.com/v3/search/#search-users + * + * @param string $q the filter + * @param string $sort the sort field + * @param string $order asc/desc + * + * @return array list of users found + */ + public function users($q, $sort = 'updated', $order = 'desc') + { + return $this->get('/search/users', array('q' => $q, 'sort' => $sort, 'order' => $order)); + } + +} diff --git a/lib/Github/Client.php b/lib/Github/Client.php index 6909264ed66..c1779663858 100644 --- a/lib/Github/Client.php +++ b/lib/Github/Client.php @@ -31,6 +31,7 @@ * @method Api\Repo repos() * @method Api\Repo repository() * @method Api\Repo repositories() + * @method Api\Search search() * @method Api\Organization team() * @method Api\Organization teams() * @method Api\User user() @@ -162,6 +163,10 @@ public function api($name) $api = new Api\Repo($this); break; + case 'search': + $api = new Api\Search($this); + break; + case 'team': case 'teams': $api = new Api\Organization\Teams($this); @@ -310,7 +315,7 @@ public function getSupportedApiVersions() /** * @param string $name - * + * * @return ApiInterface * * @throws InvalidArgumentException diff --git a/test/Github/Tests/Api/SearchTest.php b/test/Github/Tests/Api/SearchTest.php new file mode 100644 index 00000000000..d5fe9b08494 --- /dev/null +++ b/test/Github/Tests/Api/SearchTest.php @@ -0,0 +1,183 @@ + '0')); + + $api = $this->getApiMock(); + + $api->expects($this->once()) + ->method('get') + ->with( + '/search/repositories', + array('q' => 'query text', 'sort' => 'updated', 'order' => 'desc') + ) + ->will($this->returnValue($expectedArray)); + + $this->assertEquals($expectedArray, $api->repositories('query text')); + } + + /** + * @test + */ + public function shouldSearchRepositoriesRegardingSortAndOrder() + { + $expectedArray = array(array('total_count' => '0')); + + $api = $this->getApiMock(); + + $api->expects($this->once()) + ->method('get') + ->with( + '/search/repositories', + array('q' => 'query text', 'sort' => 'created', 'order' => 'asc') + ) + ->will($this->returnValue($expectedArray)); + + $this->assertEquals( + $expectedArray, + $api->repositories('query text', 'created', 'asc') + ); + } + + /** + * @test + */ + public function shouldSearchIssuesByQuery() + { + $expectedArray = array(array('total_count' => '0')); + + $api = $this->getApiMock(); + + $api->expects($this->once()) + ->method('get') + ->with( + '/search/issues', + array('q' => 'query text', 'sort' => 'updated', 'order' => 'desc') + ) + ->will($this->returnValue($expectedArray)); + + $this->assertEquals($expectedArray, $api->issues('query text')); + } + + /** + * @test + */ + public function shouldSearchIssuesRegardingSortAndOrder() + { + $expectedArray = array(array('total_count' => '0')); + + $api = $this->getApiMock(); + + $api->expects($this->once()) + ->method('get') + ->with( + '/search/issues', + array('q' => 'query text', 'sort' => 'created', 'order' => 'asc') + ) + ->will($this->returnValue($expectedArray)); + + $this->assertEquals( + $expectedArray, + $api->issues('query text', 'created', 'asc') + ); + } + + /** + * @test + */ + public function shouldSearchCodeByQuery() + { + $expectedArray = array(array('total_count' => '0')); + + $api = $this->getApiMock(); + + $api->expects($this->once()) + ->method('get') + ->with( + '/search/code', + array('q' => 'query text', 'sort' => 'updated', 'order' => 'desc') + ) + ->will($this->returnValue($expectedArray)); + + $this->assertEquals($expectedArray, $api->code('query text')); + } + + /** + * @test + */ + public function shouldSearchCodeRegardingSortAndOrder() + { + $expectedArray = array(array('total_count' => '0')); + + $api = $this->getApiMock(); + + $api->expects($this->once()) + ->method('get') + ->with( + '/search/code', + array('q' => 'query text', 'sort' => 'created', 'order' => 'asc') + ) + ->will($this->returnValue($expectedArray)); + + $this->assertEquals( + $expectedArray, + $api->code('query text', 'created', 'asc') + ); + } + + /** + * @test + */ + public function shouldSearchUsersByQuery() + { + $expectedArray = array(array('total_count' => '0')); + + $api = $this->getApiMock(); + + $api->expects($this->once()) + ->method('get') + ->with( + '/search/users', + array('q' => 'query text', 'sort' => 'updated', 'order' => 'desc') + ) + ->will($this->returnValue($expectedArray)); + + $this->assertEquals($expectedArray, $api->users('query text')); + } + + /** + * @test + */ + public function shouldSearchUsersRegardingSortAndOrder() + { + $expectedArray = array(array('total_count' => '0')); + + $api = $this->getApiMock(); + + $api->expects($this->once()) + ->method('get') + ->with( + '/search/users', + array('q' => 'query text', 'sort' => 'created', 'order' => 'asc') + ) + ->will($this->returnValue($expectedArray)); + + $this->assertEquals( + $expectedArray, + $api->users('query text', 'created', 'asc') + ); + } + + protected function getApiClass() + { + return 'Github\Api\Search'; + } +} diff --git a/test/Github/Tests/ClientTest.php b/test/Github/Tests/ClientTest.php index 04b3a710397..b7a8751fb39 100644 --- a/test/Github/Tests/ClientTest.php +++ b/test/Github/Tests/ClientTest.php @@ -186,6 +186,8 @@ public function getApiClassesProvider() array('repository', 'Github\Api\Repo'), array('repositories', 'Github\Api\Repo'), + array('search', 'Github\Api\Search'), + array('pr', 'Github\Api\PullRequest'), array('pullRequest', 'Github\Api\PullRequest'), array('pull_request', 'Github\Api\PullRequest'),