diff --git a/doc/index.md b/doc/index.md index e278e2c931b..f3164aa16c3 100644 --- a/doc/index.md +++ b/doc/index.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) 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 index 51343a88585..f8f3dbac953 100644 --- a/lib/Github/Api/Deployment.php +++ b/lib/Github/Api/Deployment.php @@ -4,20 +4,33 @@ use Github\Exception\MissingArgumentException; +/** + * Listing, creating and updating deployments. + * + * @link https://developer.github.com/v3/repos/deployments/ + */ class Deployment extends AbstractApi { - + /** + * List deployments for a particular repository + * @link https://developer.github.com/v3/repos/deployments/#list-deployments + * + * @param string $username the username of the user who owns the repository + * @param string $repository the name of the repository + * @param array $params query parameters to filter deployments by (see link) + * @return array the deployments requested + */ public function all($username, $repository, array $params = array()) { - return $this->get('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/deployments', array(), - array('Accept' => 'application/vnd.github.cannonball-preview+json') - ); + return $this->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 @@ -32,22 +45,40 @@ public function create($username, $repository, array $params) throw new MissingArgumentException(array('ref')); } - return $this->post('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/deployments', $params, ['Accept' => 'application/vnd.github.cannonball-preview+json']); + return $this->post('repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/deployments', $params); } /** - * Update deployment information's by username, repo and deployment number. Requires authentication. + * 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 $username the username * @param string $repository the repository - * @param string $id the deployment number + * @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 update($username, $repository, $id, array $params) + 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, ['Accept' => 'application/vnd.github.cannonball-preview+json']); + 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/test/Github/Tests/Api/DeploymentTest.php b/test/Github/Tests/Api/DeploymentTest.php new file mode 100644 index 00000000000..8334f8fd3ea --- /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 = ["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 = ["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 = [ "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'; + } +}