Deployments: added missing 'delete deployment' endpoint

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

@@ -66,6 +66,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
      */