Merge pull request #932 from acrobat/improve-checks-api

Improve checks api implementation

Author: acrobat

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)

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);
+```
+
+
+
+

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);
+```

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)

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.
      *

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 <zack.galbreath@kitware.com>
  */
@@ -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');
     }
 }

lib/Github/Api/Repository/Checks/CheckRuns.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace Github\Api\Repository\Checks;
+
+use Github\Api\AbstractApi;
+
+/**
+ * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks
+ */
+class CheckRuns extends AbstractApi
+{
+    /**
+     * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#create-a-check-run
+     *
+     * @return array
+     */
+    public function create(string $username, string $repository, array $params = [])
+    {
+        return $this->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);
+    }
+}

lib/Github/Api/Repository/Checks/CheckSuites.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace Github\Api\Repository\Checks;
+
+use Github\Api\AbstractApi;
+
+/**
+ * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks
+ */
+class CheckSuites extends AbstractApi
+{
+    /**
+     * @link https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#create-a-check-suite
+     *
+     * @return array
+     */
+    public function create(string $username, string $repository, array $params = [])
+    {
+        return $this->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);
+    }
+}