diff --git a/doc/README.md b/doc/README.md index 26ddcd6fbd0..361cdaaba8b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -48,7 +48,8 @@ v3 APIs: * [Reviews](pull_request/reviews.md) * [Rate Limits](rate_limits.md) * [Repositories](repos.md) - * [Checks](repo/checks.md) + * [Check Runs](repo/check_runs.md) + * [Check Suites](repo/check_suites.md) * [Contents](repo/contents.md) * [Deployments](repo/deployments.md) * [Labels](repo/labels.md) diff --git a/doc/repo/check_runs.md b/doc/repo/check_runs.md new file mode 100644 index 00000000000..87109e07e69 --- /dev/null +++ b/doc/repo/check_runs.md @@ -0,0 +1,67 @@ +## Repo / Checks runs API +[Back to the "Repos API"](../repos.md) | [Back to the navigation](../README.md) + +### Create a check run + +[Visit GitHub for a full of list of parameters and their descriptions.](https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#create-a-check-run) + +```php +$params = [ + 'name' => 'my check', # required + 'head_sha' => $commitSha, # required + 'status' => 'queued', + 'output' => [/*...*/] +]; +$check = $client->api('repo')->checkRuns()->create('KnpLabs', 'php-github-api', $params); +``` + +### Get a check run + +https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#get-a-check-run + +```php +$check = $client->api('repo')->checkRuns()->show('KnpLabs', 'php-github-api', $checkRunId); +``` + +### Update an existing check run + +https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#update-a-check-run + +```php +$params = [ + 'name' => 'my check', + 'status' => 'in_progress', + 'output' => [/*...*/] +]; +$check = $client->api('repo')->checkRuns()->update('KnpLabs', 'php-github-api', $checkRunId, $params); +``` + +### List check run annotations + +https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#list-check-run-annotations + +```php +$annotations = $client->api('repo')->checkRuns()->annotations('KnpLabs', 'php-github-api', $checkRunId); +``` + +### List check runs for a check suite + +https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#list-check-runs-in-a-check-suite + +```php +$params = [/*...*/]; +$checks = $client->api('repo')->checkRuns()->allForCheckSuite('KnpLabs', 'php-github-api', $checkSuiteId, $params); +``` + +### List check runs for a Git reference + +https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#list-check-runs-for-a-git-reference + +```php +$params = [/*...*/]; +$checks = $client->api('repo')->checkRuns()->allForReference('KnpLabs', 'php-github-api', $reference, $params); +``` + + + + diff --git a/doc/repo/check_suites.md b/doc/repo/check_suites.md new file mode 100644 index 00000000000..7131674b510 --- /dev/null +++ b/doc/repo/check_suites.md @@ -0,0 +1,48 @@ +## Repo / Check suites API +[Back to the "Repos API"](../repos.md) | [Back to the navigation](../README.md) + +### Create a check suite + +https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#create-a-check-suite + +```php +$params = [ + 'head_sha' => $commitSha, # required +]; +$check = $client->api('repo')->checkSuites()->create('KnpLabs', 'php-github-api', $params); +``` + +### Update check suite preferences + +https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#update-repository-preferences-for-check-suites + +```php +$params = [/*...*/]; +$check = $client->api('repo')->checkSuites()->updatePreferences('KnpLabs', 'php-github-api', $params); +``` + +### Get a check suite + +https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#get-a-check-suite + +```php +$check = $client->api('repo')->checkSuites()->getCheckSuite('KnpLabs', 'php-github-api', $checkSuiteId); +``` + +### Rerequest a check suite + +https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#rerequest-a-check-suite + +```php +$annotations = $client->api('repo')->checkSuites()->rerequest('KnpLabs', 'php-github-api', $checkSuiteId); +``` + + +### List check suites for a Git reference + +https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#list-check-suites-for-a-git-reference + +```php +$params = [/*...*/]; +$checks = $client->api('repo')->checkSuites()->allForReference('KnpLabs', 'php-github-api', $reference, $params); +``` diff --git a/doc/repo/checks.md b/doc/repo/checks.md index 3e24d9b4868..f81f1f6f8f3 100644 --- a/doc/repo/checks.md +++ b/doc/repo/checks.md @@ -1,6 +1,8 @@ ## Repo / Checks API [Back to the "Repos API"](../repos.md) | [Back to the navigation](../README.md) +**This API class is deprecated use the [Check runs](check_runs.md) and the [Check suites](check_suites.md) api classes.** + ### Create a check for a commit [Visit GitHub for a full of list of parameters and their descriptions.](https://developer.github.com/v3/checks/runs/#create-a-check-run) diff --git a/lib/Github/Api/Repo.php b/lib/Github/Api/Repo.php index 45c36099d53..76bb1baa1c1 100644 --- a/lib/Github/Api/Repo.php +++ b/lib/Github/Api/Repo.php @@ -3,6 +3,8 @@ namespace Github\Api; use Github\Api\Repository\Checks; +use Github\Api\Repository\Checks\CheckRuns; +use Github\Api\Repository\Checks\CheckSuites; use Github\Api\Repository\Collaborators; use Github\Api\Repository\Comments; use Github\Api\Repository\Commits; @@ -335,14 +337,33 @@ public function commits() * Manage checks on a repository. * * @link https://developer.github.com/v3/checks/ + * @deprecated since 2.17 and will be removed in 3.0. Use the "checkRuns" or "checkSuites" api's instead. * * @return Checks */ public function checks() { + @trigger_error(sprintf('The "%s" is deprecated since knp-labs/php-github-api 2.17 and will be removed in knp-labs/php-github-api 3.0. Use the "checkRuns" or "checkSuites" api\'s instead.', __METHOD__), E_USER_DEPRECATED); + return new Checks($this->client); } + /** + * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#check-runs + */ + public function checkRuns(): CheckRuns + { + return new CheckRuns($this->client); + } + + /** + * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#check-suites + */ + public function checkSuites(): CheckSuites + { + return new CheckSuites($this->client); + } + /** * Manage the content of a repository. * diff --git a/lib/Github/Api/Repository/Checks.php b/lib/Github/Api/Repository/Checks.php index 90ca66e7b18..b4be88668cb 100644 --- a/lib/Github/Api/Repository/Checks.php +++ b/lib/Github/Api/Repository/Checks.php @@ -7,7 +7,8 @@ use Github\Exception\MissingArgumentException; /** - * @link https://developer.github.com/v3/checks/ + * @link https://developer.github.com/v3/checks/ + * @deprecated since 2.17 and will be removed in 3.0. Use the "Github\Api\Repository\Checks\CheckRuns" or "Github\Api\Repository\Checks\CheckSuits" api classes instead. * * @author Zack Galbreath */ @@ -29,6 +30,8 @@ class Checks extends AbstractApi */ public function create($username, $repository, array $params = []) { + @trigger_error(sprintf('The "%s" method is deprecated since knp-labs/php-github-api 2.17 and will be removed in knp-labs/php-github-api 3.0. Use the "Github\Api\Repository\Checks\CheckRuns::create" method instead.', __METHOD__), E_USER_DEPRECATED); + if (!isset($params['name'], $params['head_sha'])) { throw new MissingArgumentException(['name', 'head_sha']); } @@ -48,6 +51,8 @@ public function create($username, $repository, array $params = []) */ public function update($username, $repository, $checkRunId, array $params = []) { + @trigger_error(sprintf('The "%s" method is deprecated since knp-labs/php-github-api 2.17 and will be removed in knp-labs/php-github-api 3.0. Use the "Github\Api\Repository\Checks\CheckRuns::update" method instead.', __METHOD__), E_USER_DEPRECATED); + return $this->patch('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-runs/'.rawurlencode($checkRunId), $params); } @@ -63,6 +68,8 @@ public function update($username, $repository, $checkRunId, array $params = []) */ public function all($username, $repository, $ref, $params = []) { + @trigger_error(sprintf('The "%s" method is deprecated since knp-labs/php-github-api 2.17 and will be removed in knp-labs/php-github-api 3.0. Use the "Github\Api\Repository\Checks\CheckRuns::allForReference" method instead.', __METHOD__), E_USER_DEPRECATED); + return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/commits/'.rawurlencode($ref).'/check-runs', $params); } @@ -77,6 +84,8 @@ public function all($username, $repository, $ref, $params = []) */ public function show($username, $repository, $checkRunId) { + @trigger_error(sprintf('The "%s" method is deprecated since knp-labs/php-github-api 2.17 and will be removed in knp-labs/php-github-api 3.0. Use the "Github\Api\Repository\Checks\CheckRuns::show" method instead.', __METHOD__), E_USER_DEPRECATED); + return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-runs/'.rawurlencode($checkRunId)); } @@ -91,6 +100,8 @@ public function show($username, $repository, $checkRunId) */ public function annotations($username, $repository, $checkRunId) { + @trigger_error(sprintf('The "%s" method is deprecated since knp-labs/php-github-api 2.17 and will be removed in knp-labs/php-github-api 3.0. Use the "Github\Api\Repository\Checks\CheckRuns::annotations" method instead.', __METHOD__), E_USER_DEPRECATED); + return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-runs/'.rawurlencode($checkRunId).'/annotations'); } } diff --git a/lib/Github/Api/Repository/Checks/CheckRuns.php b/lib/Github/Api/Repository/Checks/CheckRuns.php new file mode 100644 index 00000000000..6f91997e8b4 --- /dev/null +++ b/lib/Github/Api/Repository/Checks/CheckRuns.php @@ -0,0 +1,71 @@ +post('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-runs', $params); + } + + /** + * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#get-a-check-run + * + * @return array + */ + public function show(string $username, string $repository, int $checkRunId) + { + return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-runs/'.$checkRunId); + } + + /** + * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#update-a-check-run + * + * @return array + */ + public function update(string $username, string $repository, int $checkRunId, array $params = []) + { + return $this->patch('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-runs/'.$checkRunId, $params); + } + + /** + * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#list-check-run-annotations + * + * @return array + */ + public function annotations(string $username, string $repository, int $checkRunId) + { + return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-runs/'.$checkRunId.'/annotations'); + } + + /** + * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#list-check-runs-in-a-check-suite + * + * @return array + */ + public function allForCheckSuite(string $username, string $repository, int $checkSuiteId, array $params = []) + { + return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-suites/'.$checkSuiteId.'/check-runs', $params); + } + + /** + * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#list-check-runs-for-a-git-reference + * + * @return array + */ + public function allForReference(string $username, string $repository, string $ref, array $params = []) + { + return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/commits/'.rawurlencode($ref).'/check-runs', $params); + } +} diff --git a/lib/Github/Api/Repository/Checks/CheckSuites.php b/lib/Github/Api/Repository/Checks/CheckSuites.php new file mode 100644 index 00000000000..d597fed54e7 --- /dev/null +++ b/lib/Github/Api/Repository/Checks/CheckSuites.php @@ -0,0 +1,61 @@ +post('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-suites', $params); + } + + /** + * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#update-repository-preferences-for-check-suites + * + * @return array + */ + public function updatePreferences(string $username, string $repository, array $params = []) + { + return $this->patch('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-suites/preferences', $params); + } + + /** + * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#get-a-check-suite + * + * @return array + */ + public function getCheckSuite(string $username, string $repository, int $checkSuiteId) + { + return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-suites/'.$checkSuiteId); + } + + /** + * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#rerequest-a-check-suite + * + * @return array + */ + public function rerequest(string $username, string $repository, int $checkSuiteId) + { + return $this->post('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-suites/'.$checkSuiteId.'/rerequest'); + } + + /** + * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#list-check-suites-for-a-git-reference + * + * @return array + */ + public function allForReference(string $username, string $repository, string $ref, array $params = []) + { + return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/commits/'.rawurlencode($ref).'/check-suites', $params); + } +} diff --git a/test/Github/Tests/Api/Repository/Checks/CheckRunsTest.php b/test/Github/Tests/Api/Repository/Checks/CheckRunsTest.php new file mode 100644 index 00000000000..4b7ff086ec5 --- /dev/null +++ b/test/Github/Tests/Api/Repository/Checks/CheckRunsTest.php @@ -0,0 +1,109 @@ + 'success']; + $data = ['head_sha' => 'commitSHA123456', 'name' => 'my check']; + + /** @var CheckRuns|MockObject $api */ + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('post') + ->with('/repos/KnpLabs/php-github-api/check-runs', $data) + ->willReturn($expectedValue); + + $this->assertEquals($expectedValue, $api->create('KnpLabs', 'php-github-api', $data)); + } + + /** + * @test + */ + public function shouldShowSingleCheckRun() + { + /** @var CheckRuns|MockObject $api */ + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('get') + ->with('/repos/KnpLabs/php-github-api/check-runs/14'); + + $api->show('KnpLabs', 'php-github-api', 14); + } + + /** + * @test + */ + public function shouldUpdateCheck() + { + $expectedValue = ['state' => 'success']; + $data = ['head_sha' => 'commitSHA123456', 'name' => 'my check']; + + /** @var CheckRuns|MockObject $api */ + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('patch') + ->with('/repos/KnpLabs/php-github-api/check-runs/123', $data) + ->willReturn($expectedValue); + + $this->assertEquals($expectedValue, $api->update('KnpLabs', 'php-github-api', 123, $data)); + } + + /** + * @test + */ + public function shouldListCheckRunAnnotations() + { + /** @var CheckRuns|MockObject $api */ + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('get') + ->with('/repos/KnpLabs/php-github-api/check-runs/14/annotations'); + + $api->annotations('KnpLabs', 'php-github-api', 14); + } + + /** + * @test + */ + public function shouldGetAllChecksForCheckSuite() + { + $params = ['test' => true]; + /** @var CheckRuns|MockObject $api */ + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('get') + ->with('/repos/KnpLabs/php-github-api/check-suites/123/check-runs', $params); + + $api->allForCheckSuite('KnpLabs', 'php-github-api', 123, $params); + } + + /** + * @test + */ + public function shouldGetAllChecksForReference() + { + $params = ['test' => true]; + /** @var CheckRuns|MockObject $api */ + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('get') + ->with('/repos/KnpLabs/php-github-api/commits/cb4abc15424c0015b4468d73df55efb8b60a4a3d/check-runs', $params); + + $api->allForReference('KnpLabs', 'php-github-api', 'cb4abc15424c0015b4468d73df55efb8b60a4a3d', $params); + } + + protected function getApiClass(): string + { + return CheckRuns::class; + } +} diff --git a/test/Github/Tests/Api/Repository/Checks/CheckSuitsTest.php b/test/Github/Tests/Api/Repository/Checks/CheckSuitsTest.php new file mode 100644 index 00000000000..87d8831d0da --- /dev/null +++ b/test/Github/Tests/Api/Repository/Checks/CheckSuitsTest.php @@ -0,0 +1,93 @@ + 'success']; + $data = ['head_sha' => 'commitSHA123456', 'name' => 'my check']; + + /** @var CheckSuites|MockObject $api */ + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('post') + ->with('/repos/KnpLabs/php-github-api/check-suites', $data) + ->willReturn($expectedValue); + + $this->assertEquals($expectedValue, $api->create('KnpLabs', 'php-github-api', $data)); + } + + /** + * @test + */ + public function shouldUpdateCheckSuitePreferences() + { + $expectedValue = ['preferences' => []]; + $data = ['preference_1' => true]; + + /** @var CheckSuites|MockObject $api */ + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('patch') + ->with('/repos/KnpLabs/php-github-api/check-suites/preferences', $data) + ->willReturn($expectedValue); + + $this->assertEquals($expectedValue, $api->updatePreferences('KnpLabs', 'php-github-api', $data)); + } + + /** + * @test + */ + public function shouldGetCheckSuite() + { + /** @var CheckSuites|MockObject $api */ + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('get') + ->with('/repos/KnpLabs/php-github-api/check-suites/14'); + + $api->getCheckSuite('KnpLabs', 'php-github-api', 14); + } + + /** + * @test + */ + public function shouldRerequest() + { + /** @var CheckSuites|MockObject $api */ + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('post') + ->with('/repos/KnpLabs/php-github-api/check-suites/14/rerequest'); + + $api->rerequest('KnpLabs', 'php-github-api', 14); + } + + /** + * @test + */ + public function shouldGetAllCheckSuitesForReference() + { + /** @var CheckSuites|MockObject $api */ + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('get') + ->with('/repos/KnpLabs/php-github-api/commits/cb4abc15424c0015b4468d73df55efb8b60a4a3d/check-suites'); + + $api->allForReference('KnpLabs', 'php-github-api', 'cb4abc15424c0015b4468d73df55efb8b60a4a3d'); + } + + protected function getApiClass(): string + { + return CheckSuites::class; + } +}