From 87116931e3ef8a98421f21862f31aa1883e91478 Mon Sep 17 00:00:00 2001 From: Hannes Papenberg Date: Fri, 13 Nov 2026 00:17:03 +0100 Subject: [PATCH] Add the search API methods and deprecate the legacy search methods Search only wrapped the legacy search API (/legacy/...), which GitHub has removed, so every method failed. Add getCode(), getCommits(), getIssues(), getLabels(), getRepositories(), getTopics() and getUsers() for the /search/* endpoints, with the query encoded according to RFC 3986. Deprecate the legacy methods, and let issues() accept the "closed" state its error message asks for. Co-Authored-By: Claude Opus 5.5 --- Tests/Package/SearchTest.php | 97 ++++++++++++++++ composer.json | 3 +- docs/overview.md | 29 +++++ src/Package/Search.php | 211 ++++++++++++++++++++++++++++++++++- 4 files changed, 333 insertions(+), 7 deletions(-) diff --git a/Tests/Package/SearchTest.php b/Tests/Package/SearchTest.php index 7f1e636f..2aebde33 100644 --- a/Tests/Package/SearchTest.php +++ b/Tests/Package/SearchTest.php @@ -8,6 +8,8 @@ use Joomla\Github\Package\Search; use Joomla\Github\Tests\Stub\GitHubTestCase; +use PHPUnit\Framework\Attributes\DataProvider; +use PHPUnit\Framework\Attributes\IgnoreDeprecations; /** * Test class for Activity. @@ -41,8 +43,11 @@ protected function setUp(): void * * @return void */ + #[IgnoreDeprecations] public function testIssues() { + $this->expectUserDeprecationMessageMatches('/' . preg_quote('Joomla\Github\Package\Search::issues() is deprecated and will be removed in 5.0', '/') . '/'); + $this->client->expects($this->once()) ->method('get') ->with('/legacy/issues/search/joomla/joomla-platform/open/github') @@ -71,8 +76,11 @@ public function testIssuesInvalidState() * * @return void */ + #[IgnoreDeprecations] public function testRepositories() { + $this->expectUserDeprecationMessageMatches('/' . preg_quote('Joomla\Github\Package\Search::repositories() is deprecated and will be removed in 5.0', '/') . '/'); + $this->client->expects($this->once()) ->method('get') ->with('/legacy/repos/search/joomla') @@ -89,8 +97,11 @@ public function testRepositories() * * @return void */ + #[IgnoreDeprecations] public function testUsers() { + $this->expectUserDeprecationMessageMatches('/' . preg_quote('Joomla\Github\Package\Search::users() is deprecated and will be removed in 5.0', '/') . '/'); + $this->client->expects($this->once()) ->method('get') ->with('/legacy/user/search/joomla') @@ -107,8 +118,11 @@ public function testUsers() * * @return void */ + #[IgnoreDeprecations] public function testEmail() { + $this->expectUserDeprecationMessageMatches('/' . preg_quote('Joomla\Github\Package\Search::email() is deprecated and will be removed in 5.0', '/') . '/'); + $this->client->expects($this->once()) ->method('get') ->with('/legacy/user/email/email@joomla') @@ -119,4 +133,87 @@ public function testEmail() $this->equalTo(json_decode($this->sampleString)) ); } + + /** + * Tests that the legacy issues method accepts the "closed" state its message asks for + * + * @return void + */ + #[IgnoreDeprecations] + public function testIssuesClosed() + { + $this->expectUserDeprecationMessageMatches('/Search::issues\(\) is deprecated/'); + + $this->client->expects($this->once()) + ->method('get') + ->with('/legacy/issues/search/joomla/joomla-platform/closed/github') + ->willReturn($this->response); + + $this->object->issues('joomla', 'joomla-platform', 'closed', 'github'); + } + + /** + * Data provider for the search API v3 methods + * + * @return \Generator + */ + public static function seachMethodsProvider(): \Generator + { + yield 'code' => [ + 'getCode', + ['addClass in:file language:js repo:jquery/jquery', 'asc', 2, 50], + '/search/code?q=addClass%20in%3Afile%20language%3Ajs%20repo%3Ajquery%2Fjquery&order=asc&page=2&per_page=50', + ]; + yield 'commits' => [ + 'getCommits', + ['repo:joomla/joomla-cms fix', 'author-date', 'desc'], + '/search/commits?q=repo%3Ajoomla%2Fjoomla-cms%20fix&sort=author-date&order=desc', + ]; + yield 'issues' => [ + 'getIssues', + ['repo:joomla/joomla-cms is:issue label:"No Code Attached Yet" created:>2026-01-01+00:00'], + '/search/issues?q=repo%3Ajoomla%2Fjoomla-cms%20is%3Aissue%20label%3A%22No%20Code%20Attached%20Yet%22' + . '%20created%3A%3E2026-01-01%2B00%3A00', + ]; + yield 'labels' => [ + 'getLabels', + [64778136, 'bug defect', 'created'], + '/search/labels?repository_id=64778136&q=bug%20defect&sort=created', + ]; + yield 'repositories' => [ + 'getRepositories', + ['joomla language:php stars:>100', 'stars', 'desc', 1, 10], + '/search/repositories?q=joomla%20language%3Aphp%20stars%3A%3E100&sort=stars&order=desc&page=1&per_page=10', + ]; + yield 'topics' => [ + 'getTopics', + ['joomla is:featured'], + '/search/topics?q=joomla%20is%3Afeatured', + ]; + yield 'users' => [ + 'getUsers', + ['tom repos:>42 followers:>1000', 'followers'], + '/search/users?q=tom%20repos%3A%3E42%20followers%3A%3E1000&sort=followers', + ]; + } + + /** + * Tests the search API v3 methods + * + * @param string $method The method to call + * @param array $arguments The arguments + * @param string $url The expected request URL + * + * @return void + */ + #[DataProvider('seachMethodsProvider')] + public function testSearchMethods(string $method, array $arguments, string $url) + { + $this->client->expects($this->once()) + ->method('get') + ->with($url) + ->willReturn($this->response); + + $this->assertEquals(json_decode($this->sampleString), $this->object->$method(...$arguments)); + } } diff --git a/composer.json b/composer.json index 49ad2e0a..d44c9b57 100644 --- a/composer.json +++ b/composer.json @@ -9,7 +9,8 @@ "php": "^8.3.0", "joomla/http": "^4.0", "joomla/registry": "^4.0", - "joomla/uri": "^4.0" + "joomla/uri": "^4.0", + "symfony/deprecation-contracts": "^2|^3" }, "require-dev": { "phpunit/phpunit": "^12.2.7", diff --git a/docs/overview.md b/docs/overview.md index cfd53634..1109a480 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,3 +1,32 @@ # Github API package TODO + +## Search + +`$github->search` wraps GitHub's search API. Each method takes a search query in GitHub's +[search syntax](https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax), +pass it unencoded: + +| Method | Endpoint | +|---|---| +| `getCode($query, $order, $page, $limit)` | `/search/code` | +| `getCommits($query, $sort, $order, $page, $limit)` | `/search/commits` | +| `getIssues($query, $sort, $order, $page, $limit)` | `/search/issues` (issues and pull requests) | +| `getLabels($repositoryId, $query, $sort, $order, $page, $limit)` | `/search/labels` | +| `getRepositories($query, $sort, $order, $page, $limit)` | `/search/repositories` | +| `getTopics($query, $page, $limit)` | `/search/topics` | +| `getUsers($query, $sort, $order, $page, $limit)` | `/search/users` | + +```php +$result = $github->search->getIssues('repo:joomla/joomla-cms is:issue is:open label:bug', 'updated', 'desc'); + +echo $result->total_count; + +foreach ($result->items as $issue) { + echo $issue->title; +} +``` + +`issues()`, `repositories()`, `users()` and `email()` use the legacy search API, which GitHub has removed. They are +deprecated and will be removed in 5.0. diff --git a/src/Package/Search.php b/src/Package/Search.php index f1a744c0..fc574d41 100644 --- a/src/Package/Search.php +++ b/src/Package/Search.php @@ -14,7 +14,10 @@ /** * GitHub API Search class for the Joomla Framework. * - * @link https://developer.github.com/v3/search + * The methods issues(), repositories(), users() and email() use the legacy search API, which GitHub has removed; + * use the get*() methods instead. + * + * @link https://docs.github.com/en/rest/search/search * * @since 1.0 */ @@ -32,11 +35,18 @@ class Search extends AbstractPackage * * @since 1.0 * @throws \UnexpectedValueException - * @deprecated The legacy API is deprecated + * @deprecated 5.0 GitHub has removed the legacy search API. Use getIssues() instead. */ public function issues($owner, $repo, $state, $keyword) { - if (\in_array($state, ['open', 'close']) == false) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, use getIssues() instead.', + __METHOD__ + ); + + if (\in_array($state, ['open', 'closed']) == false) { throw new \UnexpectedValueException('State must be either "open" or "closed"'); } @@ -64,10 +74,17 @@ public function issues($owner, $repo, $state, $keyword) * @return object * * @since 1.0 - * @deprecated The legacy API is deprecated + * @deprecated 5.0 GitHub has removed the legacy search API. Use getRepositories() instead. */ public function repositories($keyword, $language = '', $startPage = 0) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, use getRepositories() instead.', + __METHOD__ + ); + // Build the request path. $uri = $this->fetchUrl('/legacy/repos/search/' . $keyword); @@ -94,10 +111,17 @@ public function repositories($keyword, $language = '', $startPage = 0) * @return object * * @since 1.0 - * @deprecated The legacy API is deprecated + * @deprecated 5.0 GitHub has removed the legacy search API. Use getUsers() instead. */ public function users($keyword, $startPage = 0) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, use getUsers() instead.', + __METHOD__ + ); + // Build the request path. $uri = $this->fetchUrl('/legacy/user/search/' . $keyword); @@ -122,10 +146,17 @@ public function users($keyword, $startPage = 0) * @return object * * @since 1.0 - * @deprecated The legacy API is deprecated + * @deprecated 5.0 GitHub has removed the legacy email search. There is no replacement. */ public function email($email) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has removed the legacy email search.', + __METHOD__ + ); + // Build the request path. $path = '/legacy/user/email/' . $email; @@ -134,4 +165,172 @@ public function email($email) $this->client->get($this->fetchUrl($path)) ); } + + /** + * Search code. + * + * @param string $query The search query, e.g. `addClass in:file language:js repo:jquery/jquery`. + * @param string $order The sort order, `desc` or `asc`. Empty for GitHub's default. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object An object with the properties total_count, incomplete_results and items. + * + * @link https://docs.github.com/en/rest/search/search#search-code + * @since __DEPLOY_VERSION__ + */ + public function getCode(string $query, string $order = '', int $page = 0, int $limit = 0) + { + return $this->search('code', ['q' => $query, 'order' => $order], $page, $limit); + } + + /** + * Search commits. + * + * @param string $query The search query, e.g. `repo:joomla/joomla-cms fix author:octocat`. + * @param string $sort Sort by `author-date` or `committer-date`. Empty for best match. + * @param string $order The sort order, `desc` or `asc`. Empty for GitHub's default. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object An object with the properties total_count, incomplete_results and items. + * + * @link https://docs.github.com/en/rest/search/search#search-commits + * @since __DEPLOY_VERSION__ + */ + public function getCommits(string $query, string $sort = '', string $order = '', int $page = 0, int $limit = 0) + { + return $this->search('commits', ['q' => $query, 'sort' => $sort, 'order' => $order], $page, $limit); + } + + /** + * Search issues and pull requests. + * + * @param string $query The search query, e.g. `repo:joomla/joomla-cms is:issue is:open label:bug`. + * @param string $sort Sort by `comments`, `reactions`, `interactions`, `created` or `updated`, among others. + * Empty for best match. + * @param string $order The sort order, `desc` or `asc`. Empty for GitHub's default. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object An object with the properties total_count, incomplete_results and items. + * + * @link https://docs.github.com/en/rest/search/search#search-issues-and-pull-requests + * @since __DEPLOY_VERSION__ + */ + public function getIssues(string $query, string $sort = '', string $order = '', int $page = 0, int $limit = 0) + { + return $this->search('issues', ['q' => $query, 'sort' => $sort, 'order' => $order], $page, $limit); + } + + /** + * Search labels in a repository. + * + * @param integer $repositoryId The ID of the repository. + * @param string $query The search keywords. + * @param string $sort Sort by `created` or `updated`. Empty for best match. + * @param string $order The sort order, `desc` or `asc`. Empty for GitHub's default. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object An object with the properties total_count, incomplete_results and items. + * + * @link https://docs.github.com/en/rest/search/search#search-labels + * @since __DEPLOY_VERSION__ + */ + public function getLabels(int $repositoryId, string $query, string $sort = '', string $order = '', int $page = 0, int $limit = 0) + { + return $this->search( + 'labels', + ['repository_id' => $repositoryId, 'q' => $query, 'sort' => $sort, 'order' => $order], + $page, + $limit + ); + } + + /** + * Search repositories. + * + * @param string $query The search query, e.g. `joomla language:php stars:>100`. + * @param string $sort Sort by `stars`, `forks`, `help-wanted-issues` or `updated`. Empty for best match. + * @param string $order The sort order, `desc` or `asc`. Empty for GitHub's default. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object An object with the properties total_count, incomplete_results and items. + * + * @link https://docs.github.com/en/rest/search/search#search-repositories + * @since __DEPLOY_VERSION__ + */ + public function getRepositories(string $query, string $sort = '', string $order = '', int $page = 0, int $limit = 0) + { + return $this->search('repositories', ['q' => $query, 'sort' => $sort, 'order' => $order], $page, $limit); + } + + /** + * Search topics. + * + * @param string $query The search query, e.g. `joomla is:featured`. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object An object with the properties total_count, incomplete_results and items. + * + * @link https://docs.github.com/en/rest/search/search#search-topics + * @since __DEPLOY_VERSION__ + */ + public function getTopics(string $query, int $page = 0, int $limit = 0) + { + return $this->search('topics', ['q' => $query], $page, $limit); + } + + /** + * Search users. + * + * @param string $query The search query, e.g. `tom repos:>42 followers:>1000`. + * @param string $sort Sort by `followers`, `repositories` or `joined`. Empty for best match. + * @param string $order The sort order, `desc` or `asc`. Empty for GitHub's default. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object An object with the properties total_count, incomplete_results and items. + * + * @link https://docs.github.com/en/rest/search/search#search-users + * @since __DEPLOY_VERSION__ + */ + public function getUsers(string $query, string $sort = '', string $order = '', int $page = 0, int $limit = 0) + { + return $this->search('users', ['q' => $query, 'sort' => $sort, 'order' => $order], $page, $limit); + } + + /** + * Send a search request. + * + * The query is encoded here, because Joomla\Uri\Uri does not encode the query values it renders. + * + * @param string $type The search type, e.g. `issues`. + * @param array $query The query parameters; empty values are left out. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object + * + * @since __DEPLOY_VERSION__ + */ + private function search(string $type, array $query, int $page, int $limit) + { + $query = array_filter($query, static fn ($value) => $value !== ''); + + if ($page > 0) { + $query['page'] = $page; + } + + if ($limit > 0) { + $query['per_page'] = $limit; + } + + $path = '/search/' . $type . '?' . http_build_query($query, '', '&', \PHP_QUERY_RFC3986); + + return $this->processResponse($this->client->get($this->fetchUrl($path))); + } }