Adding Deployment API - For Review

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)

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

lib/Github/Api/Deployment.php

@@ -0,0 +1,84 @@
+<?php
+
+namespace Github\Api;
+
+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', $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');
+    }
+}

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

test/Github/Tests/Api/DeploymentTest.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace Github\Tests\Api;
+
+class DeploymentTest extends TestCase
+{
+    /**
+     * @test
+     */
+    public function shouldCreateDeployment()
+    {
+        $api = $this->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';
+    }
+}