feature #991 Deployments: added missing 'delete deployment' endpoint (clxmstaab)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

this api endpoint was missing completely from the client. this is the only missing feature in 2.x for me, so it would be really cool this could be merged into 2.x.

my php constraints do not allow me to update to 3.x yet.

this PR added the endpoint as described in https://docs.github.com/en/rest/reference/repos#delete-a-deployment

Commits
-------

095f463 Deployments: added missing 'delete deployment' endpoint
6ee0e0b added test
06787a1 cs
53d5ea3 Update deployments.md
fc3e323 removed phpdocs, use native typehints

Author: clxmstaab

doc/repo/deployments.md

@@ -21,7 +21,7 @@ $deployments = $client->api('deployment')->all('KnpLabs', 'php-github-api', arra
 $deployment = $client->api('deployment')->show('KnpLabs', 'php-github-api', $id);
 ```
 
-#### Create a new deployments.
+#### Create a new deployment.
 
 The `ref` parameter is required.
 
@@ -31,9 +31,19 @@ $data = $client->api('deployment')->create('KnpLabs', 'php-github-api', array('r
 
 Please note that once a deployment is created it cannot be edited. Only status updates can be created.
 
+#### Delete a existing deployment.
+
+```php
+$deployment = $client->api('deployment')->show('KnpLabs', 'php-github-api', $id);
+```
+
+Please note that a deployment can only be deleted when in inactive state.
+Consider transitioning the status to `inactive` beforehand using `updateStatus`.
+
+
 #### Create a new status update.
 
-The `state` parameter is required. At the time of writing, this must be pending, success, error, or failure.
+The `state` parameter is required. At the time of writing, this must be pending, queued, in_progress, success, inactive, error, or failure.
 
 ```php
 $data = $client->api('deployment')->updateStatus('KnpLabs', 'php-github-api', 1, array('state' => 'error', 'description' => 'syntax error'));

lib/Github/Api/Deployment.php

@@ -68,6 +68,21 @@ public function create($username, $repository, array $params)
         return $this->post('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/deployments', $params);
     }
 
+    /**
+     * Delete a deployment for the given username and repo.
+     *
+     * @link https://docs.github.com/en/rest/reference/repos#delete-a-deployment
+     *
+     * Important: Deployments can only be deleted when in inactive state
+     * @see updateStatus
+     *
+     * @return mixed null on success, array on error with 'message'
+     */
+    public function remove(string $username, string $repository, int $id)
+    {
+        return $this->delete('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/deployments/'.$id);
+    }
+
     /**
      * Updates a deployment by creating a new status update.
      *

test/Github/Tests/Api/DeploymentTest.php

@@ -51,7 +51,7 @@ public function shouldGetAllDeploymentsWithFilterParameters()
     /**
      * @test
      */
-    public function shouldShowProject()
+    public function shouldShowDeployment()
     {
         $expectedValue = ['id' => 123, 'ref' => 'master'];
 
@@ -64,6 +64,20 @@ public function shouldShowProject()
         $this->assertEquals($expectedValue, $api->show('KnpLabs', 'php-github-api', 123));
     }
 
+    /**
+     * @test
+     */
+    public function shouldDeleteDeployment()
+    {
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('delete')
+            ->with('/repos/KnpLabs/php-github-api/deployments/123')
+            ->will($this->returnValue(null));
+
+        $this->assertNull($api->remove('KnpLabs', 'php-github-api', 123));
+    }
+
     /**
      * @test
      */