diff --git a/doc/README.md b/doc/README.md index 176e5a2b51d..5989a7d3edc 100644 --- a/doc/README.md +++ b/doc/README.md @@ -18,6 +18,7 @@ APIs: * [Contents](repo/contents.md) * [Releases](repo/releases.md) * [Assets](repo/assets.md) + * [Deployments](repo/deployments.md) * [Users](users.md) * [Meta](meta.md) * [Activity](activity.md) diff --git a/doc/repo/deployments.md b/doc/repo/deployments.md new file mode 100644 index 00000000000..386025d936f --- /dev/null +++ b/doc/repo/deployments.md @@ -0,0 +1,40 @@ +## Repo / Deployments API +[Back to the "Repos API"](../repos.md) | [Back to the navigation](../index.md) + +Provides information about deployments for a repository. Wraps [GitHub Deployments API](https://developer.github.com/v3/repos/deployments/). + +#### List all deployments. + +```php +$deployments = $client->api('deployment')->all('KnpLabs', 'php-github-api'); +``` + +You can also filter the returned results (see [the documentation](https://developer.github.com/v3/repos/deployments/#list-deployments) for more information): + +```php +$deployments = $client->api('deployment')->all('KnpLabs', 'php-github-api', array('environment' => 'production')); +``` + +#### Create a new deployments. + +The `ref` parameter is required. + +```php +$data = $client->api('deployment')->create('KnpLabs', 'php-github-api', array('ref' => 'fd6a5f9e5a430dddae8d6a8ea378f913d3a766f9')); +``` + +Please note that once a deployment is created it cannot be edited. Only status updates can be created. + +#### Create a new status update. + +The `state` parameter is required. At the time of writing, this must be pending, success, error, or failure. + +```php +$data = $client->api('deployment')->updateStatus('KnpLabs', 'php-github-api', 1, array('state' => 'error', 'description' => 'syntax error')); +``` + +#### Get all status updates for a deployment. + +```php +$statusUpdates = $client->api('deployment')->getStatuses('KnpLabs', 'php-github-api', 1); +``` diff --git a/lib/Github/Api/Deployment.php b/lib/Github/Api/Deployment.php new file mode 100644 index 00000000000..f8f3dbac953 --- /dev/null +++ b/lib/Github/Api/Deployment.php @@ -0,0 +1,84 @@ +get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/deployments', $params); + } + + /** + * Create a new deployment for the given username and repo. + * @link https://developer.github.com/v3/repos/deployments/#create-a-deployment + * + * Important: Once a deployment is created, it cannot be updated. Changes are indicated by creating new statuses. + * @see updateStatus + * + * @param string $username the username + * @param string $repository the repository + * @param array $params the new deployment data + * @return array information about the deployment + * + * @throws MissingArgumentException + */ + public function create($username, $repository, array $params) + { + if (!isset($params['ref'])) { + throw new MissingArgumentException(array('ref')); + } + + return $this->post('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/deployments', $params); + } + + /** + * Updates a deployment by creating a new status update. + * @link https://developer.github.com/v3/repos/deployments/#create-a-deployment-status + * + * @param string $username the username + * @param string $repository the repository + * @param string $id the deployment number + * @param array $params The information about the deployment update. + * Must include a "state" field of pending, success, error, or failure. + * May also be given a target_url and description, ßee link for more details. + * @return array information about the deployment + * + * @throws MissingArgumentException + */ + public function updateStatus($username, $repository, $id, array $params) + { + if (!isset($params['state'])) { + throw new MissingArgumentException(array('state')); + } + return $this->post('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/deployments/'.rawurlencode($id).'/statuses', $params); + } + + /** + * Gets all of the status updates tied to a given deployment. + * + * @param string $username the username + * @param string $repository the repository + * @param int $id the deployment identifier + * @return array the deployment statuses + */ + public function getStatuses($username, $repository, $id) { + return $this->get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/deployments/'.rawurlencode($id).'/statuses'); + } +} diff --git a/lib/Github/Client.php b/lib/Github/Client.php index e63af775507..964481aad58 100644 --- a/lib/Github/Client.php +++ b/lib/Github/Client.php @@ -120,6 +120,11 @@ public function api($name) $api = new Api\CurrentUser($this); break; + case 'deployment': + case 'deployments': + $api = new Api\Deployment($this); + break; + case 'ent': case 'enterprise': $api = new Api\Enterprise($this); diff --git a/test/Github/Tests/Api/DeploymentTest.php b/test/Github/Tests/Api/DeploymentTest.php new file mode 100644 index 00000000000..2bcbb4d5d25 --- /dev/null +++ b/test/Github/Tests/Api/DeploymentTest.php @@ -0,0 +1,93 @@ +getApiMock(); + $deploymentData = array('ref' => 'fd6a5f9e5a430dddae8d6a8ea378f913d3a766f9'); + $api->expects($this->once()) + ->method('post') + ->with('repos/KnpLabs/php-github-api/deployments', $deploymentData); + + $api->create('KnpLabs', 'php-github-api', $deploymentData); + } + + /** + * @test + */ + public function shouldGetAllDeployments() + { + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('get') + ->with('repos/KnpLabs/php-github-api/deployments'); + + $api->all('KnpLabs', 'php-github-api'); + } + + /** + * @test + */ + public function shouldGetAllDeploymentsWithFilterParameters() + { + $api = $this->getApiMock(); + $filterData = array('foo' => 'bar', 'bar' => 'foo'); + + $api->expects($this->once()) + ->method('get') + ->with('repos/KnpLabs/php-github-api/deployments', $filterData); + + $api->all('KnpLabs', 'php-github-api', $filterData); + } + + /** + * @test + */ + public function shouldCreateStatusUpdate() + { + $api = $this->getApiMock(); + $statusData = array('state' => 'pending', 'description' => 'waiting to start'); + + $api->expects($this->once()) + ->method('post') + ->with('repos/KnpLabs/php-github-api/deployments/1/statuses', $statusData); + + $api->updateStatus('KnpLabs', 'php-github-api', 1, $statusData); + } + + /** + * @test + * @expectedException GitHub\Exception\MissingArgumentException + */ + public function shouldRejectStatusUpdateWithoutStateField() + { + $api = $this->getApiMock(); + $statusData = array('description' => 'waiting to start'); + + $api->updateStatus('KnpLabs', 'php-github-api', 1, $statusData); + } + + /** + * @test + */ + public function shouldGetAllStatuses() + { + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('get') + ->with('repos/KnpLabs/php-github-api/deployments/1/statuses'); + + $api->getStatuses('KnpLabs', 'php-github-api', 1); + } + + protected function getApiClass() + { + return 'Github\Api\Deployment'; + } +}