diff --git a/Tests/Package/Orgs/TeamsTest.php b/Tests/Package/Orgs/TeamsTest.php index a95123e8..96170cad 100644 --- a/Tests/Package/Orgs/TeamsTest.php +++ b/Tests/Package/Orgs/TeamsTest.php @@ -9,6 +9,8 @@ use Joomla\Github\Package\Orgs\Teams; use Joomla\Github\Tests\Stub\GitHubTestCase; +use PHPUnit\Framework\Attributes\DataProvider; +use PHPUnit\Framework\Attributes\IgnoreDeprecations; /** * Test method. @@ -599,4 +601,121 @@ public function testGetUserTeams() $this->equalTo(json_decode($this->sampleString)) ); } + + /** + * Data provider for the team methods addressing a team by organization and slug + * + * @return \Generator + */ + public static function slugMethodsProvider(): \Generator + { + yield 'getBySlug' => ['get', 'getBySlug', ['joomla', 'cms-maintainers'], ['/orgs/joomla/teams/cms-maintainers'], 200]; + yield 'editBySlug' => [ + 'patch', + 'editBySlug', + ['joomla', 'cms-maintainers', null, 'Maintainers of the CMS'], + ['/orgs/joomla/teams/cms-maintainers', '{"description":"Maintainers of the CMS"}'], + 200, + ]; + yield 'deleteBySlug' => ['delete', 'deleteBySlug', ['joomla', 'cms-maintainers'], ['/orgs/joomla/teams/cms-maintainers'], 204]; + yield 'getListMembersBySlug' => [ + 'get', + 'getListMembersBySlug', + ['joomla', 'cms-maintainers', 2, 50], + ['/orgs/joomla/teams/cms-maintainers/members?page=2&per_page=50'], + 200, + ]; + yield 'addMembershipBySlug' => [ + 'put', + 'addMembershipBySlug', + ['joomla', 'cms-maintainers', 'octocat', 'maintainer'], + ['/orgs/joomla/teams/cms-maintainers/memberships/octocat', '{"role":"maintainer"}'], + 200, + ]; + yield 'removeMembershipBySlug' => [ + 'delete', + 'removeMembershipBySlug', + ['joomla', 'cms-maintainers', 'octocat'], + ['/orgs/joomla/teams/cms-maintainers/memberships/octocat'], + 204, + ]; + yield 'getListReposBySlug' => [ + 'get', + 'getListReposBySlug', + ['joomla', 'cms-maintainers'], + ['/orgs/joomla/teams/cms-maintainers/repos'], + 200, + ]; + yield 'addRepoBySlug' => [ + 'put', + 'addRepoBySlug', + ['joomla', 'cms-maintainers', 'joomla', 'joomla-cms', 'maintain'], + ['/orgs/joomla/teams/cms-maintainers/repos/joomla/joomla-cms', '{"permission":"maintain"}'], + 204, + ]; + yield 'removeRepoBySlug' => [ + 'delete', + 'removeRepoBySlug', + ['joomla', 'cms-maintainers', 'joomla', 'joomla-cms'], + ['/orgs/joomla/teams/cms-maintainers/repos/joomla/joomla-cms'], + 204, + ]; + } + + /** + * Tests the team methods addressing a team by organization and slug + * + * @param string $httpMethod The expected HTTP method + * @param string $method The method to call + * @param array $arguments The arguments + * @param array $request The expected request arguments + * @param integer $code The response code + * + * @return void + */ + #[DataProvider('slugMethodsProvider')] + public function testSlugMethods(string $httpMethod, string $method, array $arguments, array $request, int $code) + { + $this->client->expects($this->once()) + ->method($httpMethod) + ->with(...$request) + ->willReturn($this->getResponseObject($code === 204 ? '' : $this->sampleString, $code)); + + $this->object->$method(...$arguments); + } + + /** + * Tests getMembershipBySlug and checkRepoBySlug + * + * @return void + */ + public function testMembershipAndRepoChecksBySlug() + { + $this->client->expects($this->exactly(3)) + ->method('get') + ->willReturnOnConsecutiveCalls( + $this->getResponseObject('{"state":"active","role":"member"}', 200), + $this->getResponseObject('', 404), + $this->getResponseObject('', 204) + ); + + $this->assertSame('active', $this->object->getMembershipBySlug('joomla', 'cms-maintainers', 'octocat')); + $this->assertFalse($this->object->getMembershipBySlug('joomla', 'cms-maintainers', 'nobody')); + $this->assertTrue($this->object->checkRepoBySlug('joomla', 'cms-maintainers', 'joomla', 'joomla-cms')); + } + + /** + * Tests that the methods using the legacy /teams/{team_id} routes are deprecated + * + * @return void + */ + #[IgnoreDeprecations] + public function testLegacyRoutesAreDeprecated() + { + $this->expectUserDeprecationMessageMatches('/Teams::get\(\) is deprecated and will be removed in 5\.0.*getBySlug\(\)/'); + + $this->client->method('get')->willReturn($this->response); + + $this->object->get(123); + } } 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..edd25de1 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,3 +1,25 @@ # Github API package TODO + +## Teams + +GitHub addresses teams by organization and slug (`/orgs/{org}/teams/{team_slug}`); the `/teams/{team_id}` routes are +legacy. `$github->orgs->teams` has a `…BySlug()` method for each of them: + +| Method | Replaces | +|---|---| +| `getBySlug($org, $slug)` | `get($id)` | +| `editBySlug($org, $slug, $name, $description, $privacy)` | `edit($id, ...)` | +| `deleteBySlug($org, $slug)` | `delete($id)` | +| `getListMembersBySlug($org, $slug, $page, $limit)` | `getListMembers($id)` | +| `getMembershipBySlug($org, $slug, $user)` | `getTeamMembership($id, $user)`, `isMember($id, $user)` | +| `addMembershipBySlug($org, $slug, $user, $role)` | `addTeamMembership($id, $user, $role)`, `addMember($id, $user)` | +| `removeMembershipBySlug($org, $slug, $user)` | `removeTeamMembership($id, $user)`, `removeMember($id, $user)` | +| `getListReposBySlug($org, $slug, $page, $limit)` | `getListRepos($id)` | +| `checkRepoBySlug($org, $slug, $owner, $repo)` | `checkRepo($id, $owner, $repo)` | +| `addRepoBySlug($org, $slug, $owner, $repo, $permission)` | `addRepo($id, $org, $repo)` | +| `removeRepoBySlug($org, $slug, $owner, $repo)` | `removeRepo($id, $owner, $repo)` | + +The methods in the right column are deprecated and will be removed in 5.0. `getList($org)`, `create($org, ...)` and +`getUserTeams()` already use the current routes. diff --git a/src/Package/Orgs/Teams.php b/src/Package/Orgs/Teams.php index 7aaa82eb..650464a9 100644 --- a/src/Package/Orgs/Teams.php +++ b/src/Package/Orgs/Teams.php @@ -50,9 +50,17 @@ public function getList($org) * @return object * * @since 1.0 + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use getBySlug() instead. */ public function get($id) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use getBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = '/teams/' . (int) $id; @@ -122,9 +130,17 @@ public function create($org, $name, array $repoNames = [], $permission = '') * * @since 1.0 * @throws \UnexpectedValueException + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use editBySlug() instead. */ public function edit($id, $name, $permission = '') { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use editBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = '/teams/' . (int) $id; @@ -155,9 +171,17 @@ public function edit($id, $name, $permission = '') * @return object * * @since 1.0 + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use deleteBySlug() instead. */ public function delete($id) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use deleteBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = '/teams/' . $id; @@ -177,9 +201,17 @@ public function delete($id) * @return object * * @since 1.0 + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use getListMembersBySlug() instead. */ public function getListMembers($id) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use getListMembersBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = '/teams/' . $id . '/members'; @@ -200,10 +232,17 @@ public function getListMembers($id) * * @since 1.0 * @throws \UnexpectedValueException - * @deprecated Use getTeamMembership() instead + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use getMembershipBySlug() instead. */ public function isMember($id, $user) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use getMembershipBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = '/teams/' . $id . '/members/' . $user; @@ -235,10 +274,17 @@ public function isMember($id, $user) * @return object * * @since 1.0 - * @deprecated Use addTeamMembership() instead + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use addMembershipBySlug() instead. */ public function addMember($id, $user) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use addMembershipBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = '/teams/' . $id . '/members/' . $user; @@ -261,10 +307,17 @@ public function addMember($id, $user) * @return object * * @since 1.0 - * @deprecated Use removeTeamMembership() instead + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use removeMembershipBySlug() instead. */ public function removeMember($id, $user) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use removeMembershipBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = '/teams/' . $id . '/members/' . $user; @@ -286,9 +339,17 @@ public function removeMember($id, $user) * * @since 1.4.0 * @throws \UnexpectedValueException + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use getMembershipBySlug() instead. */ public function getTeamMembership($id, $user) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use getMembershipBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = "/teams/$id/memberships/$user"; @@ -325,9 +386,17 @@ public function getTeamMembership($id, $user) * * @since 1.4.0 * @throws \UnexpectedValueException + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use addMembershipBySlug() instead. */ public function addTeamMembership($id, $user, $role = 'member') { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use addMembershipBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = "/teams/$id/memberships/$user"; @@ -356,9 +425,17 @@ public function addTeamMembership($id, $user, $role = 'member') * * @since 1.4.0 * @throws \UnexpectedValueException + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use removeMembershipBySlug() instead. */ public function removeTeamMembership($id, $user) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use removeMembershipBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = "/teams/$id/memberships/$user"; @@ -373,9 +450,17 @@ public function removeTeamMembership($id, $user) * @return object * * @since 1.0 + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use getListReposBySlug() instead. */ public function getListRepos($id) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use getListReposBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = '/teams/' . $id . '/repos'; @@ -395,9 +480,17 @@ public function getListRepos($id) * * @since 1.0 * @throws \UnexpectedValueException + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use checkRepoBySlug() instead. */ public function checkRepo($id, $owner, $repo) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use checkRepoBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = '/teams/' . $id . '/repos/' . $owner . '/' . $repo; @@ -434,9 +527,17 @@ public function checkRepo($id, $owner, $repo) * @return object * * @since 1.0 + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use addRepoBySlug() instead. */ public function addRepo($id, $org, $repo) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use addRepoBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = '/teams/' . $id . '/repos/' . $org . '/' . $repo; @@ -460,9 +561,17 @@ public function addRepo($id, $org, $repo) * @return object * * @since 1.0 + * @deprecated 5.0 GitHub has replaced the /teams/{team_id} routes. Use removeRepoBySlug() instead. */ public function removeRepo($id, $owner, $repo) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, GitHub has replaced the /teams/{team_id} routes. Use removeRepoBySlug() instead.', + __METHOD__ + ); + // Build the request path. $path = '/teams/' . (int) $id . '/repos/' . $owner . '/' . $repo; @@ -494,4 +603,270 @@ public function getUserTeams($page = 0, $limit = 0) $this->client->get($this->fetchUrl($path, $page, $limit)) ); } + + /** + * Get a team by its slug. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * + * @return object + * + * @link https://docs.github.com/en/rest/teams/teams#get-a-team-by-name + * @since __DEPLOY_VERSION__ + */ + public function getBySlug(string $org, string $slug) + { + return $this->processResponse($this->client->get($this->fetchUrl($this->slugPath($org, $slug)))); + } + + /** + * Edit a team. Only the given values are changed. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * @param string|null $name The name of the team. + * @param string|null $description The description of the team. + * @param string|null $privacy The privacy level of the team, `secret` or `closed`. + * + * @return object + * + * @link https://docs.github.com/en/rest/teams/teams#update-a-team + * @since __DEPLOY_VERSION__ + */ + public function editBySlug(string $org, string $slug, ?string $name = null, ?string $description = null, ?string $privacy = null) + { + $data = array_filter( + ['name' => $name, 'description' => $description, 'privacy' => $privacy], + static fn ($value) => $value !== null + ); + + return $this->processResponse( + $this->client->patch($this->fetchUrl($this->slugPath($org, $slug)), json_encode($data)) + ); + } + + /** + * Delete a team. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * + * @return object + * + * @link https://docs.github.com/en/rest/teams/teams#delete-a-team + * @since __DEPLOY_VERSION__ + */ + public function deleteBySlug(string $org, string $slug) + { + return $this->processResponse($this->client->delete($this->fetchUrl($this->slugPath($org, $slug))), 204); + } + + /** + * List the members of a team. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/en/rest/teams/members#list-team-members + * @since __DEPLOY_VERSION__ + */ + public function getListMembersBySlug(string $org, string $slug, int $page = 0, int $limit = 0) + { + return $this->processResponse( + $this->client->get($this->fetchUrl($this->slugPath($org, $slug) . '/members', $page, $limit)) + ); + } + + /** + * Get the team membership of a user. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * @param string $user The name of the user. + * + * @return string|boolean The state of the membership (`active` or `pending`), or false if the user is not a member. + * + * @link https://docs.github.com/en/rest/teams/members#get-team-membership-for-a-user + * @since __DEPLOY_VERSION__ + * @throws \UnexpectedValueException + */ + public function getMembershipBySlug(string $org, string $slug, string $user) + { + $response = $this->client->get($this->fetchUrl($this->slugPath($org, $slug) . '/memberships/' . $user)); + + switch ($response->getStatusCode()) { + case 200: + return json_decode((string) $response->getBody())->state; + + case 404: + return false; + + default: + throw new \UnexpectedValueException('Unexpected response code: ' . $response->getStatusCode()); + } + } + + /** + * Add or update the team membership of a user. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * @param string $user The name of the user. + * @param string $role The role of the user in the team, `member` or `maintainer`. + * + * @return object + * + * @link https://docs.github.com/en/rest/teams/members#add-or-update-team-membership-for-a-user + * @since __DEPLOY_VERSION__ + * @throws \UnexpectedValueException + */ + public function addMembershipBySlug(string $org, string $slug, string $user, string $role = 'member') + { + if (\in_array($role, ['member', 'maintainer']) == false) { + throw new \UnexpectedValueException('Roles must be either "member" or "maintainer".'); + } + + return $this->processResponse( + $this->client->put( + $this->fetchUrl($this->slugPath($org, $slug) . '/memberships/' . $user), + json_encode(['role' => $role]) + ) + ); + } + + /** + * Remove the team membership of a user. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * @param string $user The name of the user. + * + * @return object + * + * @link https://docs.github.com/en/rest/teams/members#remove-team-membership-for-a-user + * @since __DEPLOY_VERSION__ + */ + public function removeMembershipBySlug(string $org, string $slug, string $user) + { + return $this->processResponse( + $this->client->delete($this->fetchUrl($this->slugPath($org, $slug) . '/memberships/' . $user)), + 204 + ); + } + + /** + * List the repositories of a team. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/en/rest/teams/teams#list-team-repositories + * @since __DEPLOY_VERSION__ + */ + public function getListReposBySlug(string $org, string $slug, int $page = 0, int $limit = 0) + { + return $this->processResponse( + $this->client->get($this->fetchUrl($this->slugPath($org, $slug) . '/repos', $page, $limit)) + ); + } + + /** + * Check whether a team has access to a repository. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * @param string $owner The owner of the repository. + * @param string $repo The name of the repository. + * + * @return boolean + * + * @link https://docs.github.com/en/rest/teams/teams#check-team-permissions-for-a-repository + * @since __DEPLOY_VERSION__ + * @throws \UnexpectedValueException + */ + public function checkRepoBySlug(string $org, string $slug, string $owner, string $repo) + { + $response = $this->client->get($this->fetchUrl($this->slugPath($org, $slug) . '/repos/' . $owner . '/' . $repo)); + + switch ($response->getStatusCode()) { + case 200: + case 204: + return true; + + case 404: + return false; + + default: + throw new \UnexpectedValueException('Unexpected response code: ' . $response->getStatusCode()); + } + } + + /** + * Add a repository to a team or update the team's permission on it. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * @param string $owner The owner of the repository. + * @param string $repo The name of the repository. + * @param string|null $permission The permission, e.g. `pull`, `triage`, `push`, `maintain` or `admin`. + * + * @return object + * + * @link https://docs.github.com/en/rest/teams/teams#add-or-update-team-repository-permissions + * @since __DEPLOY_VERSION__ + */ + public function addRepoBySlug(string $org, string $slug, string $owner, string $repo, ?string $permission = null) + { + $data = $permission === null ? '' : json_encode(['permission' => $permission]); + + return $this->processResponse( + $this->client->put($this->fetchUrl($this->slugPath($org, $slug) . '/repos/' . $owner . '/' . $repo), $data), + 204 + ); + } + + /** + * Remove a repository from a team. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * @param string $owner The owner of the repository. + * @param string $repo The name of the repository. + * + * @return object + * + * @link https://docs.github.com/en/rest/teams/teams#remove-a-repository-from-a-team + * @since __DEPLOY_VERSION__ + */ + public function removeRepoBySlug(string $org, string $slug, string $owner, string $repo) + { + return $this->processResponse( + $this->client->delete($this->fetchUrl($this->slugPath($org, $slug) . '/repos/' . $owner . '/' . $repo)), + 204 + ); + } + + /** + * Build the path of a team in an organization. + * + * @param string $org The name of the organization. + * @param string $slug The slug of the team name. + * + * @return string + * + * @since __DEPLOY_VERSION__ + */ + private function slugPath(string $org, string $slug): string + { + return '/orgs/' . $org . '/teams/' . rawurlencode($slug); + } }