diff --git a/doc/organization/webhooks.md b/doc/organization/webhooks.md new file mode 100644 index 00000000000..4844748fa20 --- /dev/null +++ b/doc/organization/webhooks.md @@ -0,0 +1,95 @@ +## Organization / Webhooks API +[Back to the navigation](README.md) + +Listing, showing, creating, updating, testing and removing organizations webhooks. +Wraps [GitHub Organization Webhooks API](https://developer.github.com/v3/orgs/hooks/). + +Additional APIs: +* [Organization](issue/organization.md) + +### List webhooks for an organization + +> Requires [authentication](security.md). + +```php +$webhooks = $client->organization()->all('KnpLabs'); +``` + +Returns an array of webhooks for the organization. + +### Get a webhook for an organization + +> Requires [authentication](security.md). + +```php +$webhook = $client->organization()->show('KnpLabs', 123); +``` + +Returns the webhook with the ID 123 as an array for the organization. + +### Create a new webhook for an organization + +> Requires [authentication](security.md). + +```php +$webhook = $client->organization()->create('KnpLabs', array( + 'name' => 'web', + 'active' => true, + 'events' => array( + 'push', + 'pull_request' + ), + 'config' => array( + 'url' => 'http=>//example.com/webhook', + 'content_type' => 'json' + ) +)); +``` + +Creates a new webhook for the organization. +*name* and *url* parameters are required. + +The create webhook will be returned as an array. + +### Update an existing webhook for an organization + +> Requires [authentication](security.md). + +```php +$success = $client->organization()->update('KnpLabs', 123, array( + 'active' => true, + 'events' => array( + 'push', + 'pull_request' + ), + 'config' => array( + 'url' => 'http=>//example.com/webhook', + 'content_type' => 'json' + ) +)); +``` + +Update an existing webhook with ID 123 for the organization. +*url* parameter is required. + +In case of success, an array of informations about the webhook will be returned. + +### Ping a webhook for an organization + +> Requires [authentication](security.md). + +```php +$client->organization()->pings('KnpLabs', 123); +``` + +No content is returned. + +### Delete a webhook for an organization + +> Requires [authentication](security.md). + +```php +$client->organization()->delete('KnpLabs', 123); +``` + +No content is returned. \ No newline at end of file diff --git a/lib/Github/Api/Organization.php b/lib/Github/Api/Organization.php index 37322b218d8..a506702dae3 100644 --- a/lib/Github/Api/Organization.php +++ b/lib/Github/Api/Organization.php @@ -2,6 +2,7 @@ namespace Github\Api; +use Github\Api\Organization\Hooks; use Github\Api\Organization\Members; use Github\Api\Organization\Teams; @@ -58,6 +59,14 @@ public function members() return new Members($this->client); } + /** + * @return Hooks + */ + public function hooks() + { + return new Hooks($this->client); + } + /** * @return Teams */ diff --git a/lib/Github/Api/Organization/Hooks.php b/lib/Github/Api/Organization/Hooks.php new file mode 100644 index 00000000000..109b7b3b6d6 --- /dev/null +++ b/lib/Github/Api/Organization/Hooks.php @@ -0,0 +1,97 @@ +get('orgs/'.rawurlencode($organization).'/hooks'); + } + + /** + * Get a single hook. + * @link https://developer.github.com/v3/orgs/hooks/#get-single-hook + * + * @param string $organization + * @param int $id + * @return array + */ + public function show($organization, $id) + { + return $this->get('orgs/'.rawurlencode($organization).'/hooks/'.rawurlencode($id)); + } + + /** + * Create a hook. + * + * @link https://developer.github.com/v3/orgs/hooks/#create-a-hook + * @param string $organization + * @param array $params + * @return array + * @throws \Github\Exception\MissingArgumentException + */ + public function create($organization, array $params) + { + if (!isset($params['name'], $params['config'])) { + throw new MissingArgumentException(array('name', 'config')); + } + + return $this->post('orgs/'.rawurlencode($organization).'/hooks', $params); + } + + /** + * Edit a hook. + * + * @link https://developer.github.com/v3/orgs/hooks/#edit-a-hook + * @param string $organization + * @param int $id + * @param array $params + * @return array + * @throws \Github\Exception\MissingArgumentException + */ + public function update($organization, $id, array $params) + { + if (!isset($params['config'])) { + throw new MissingArgumentException(array('config')); + } + + return $this->patch('orgs/'.rawurlencode($organization).'/hooks/'.rawurlencode($id), $params); + } + + /** + * Ping a hook. + * + * @link https://developer.github.com/v3/orgs/hooks/#ping-a-hook + * @param string $organization + * @param int $id + * @return null + */ + public function ping($organization, $id) + { + return $this->post('orgs/'.rawurlencode($organization).'/hooks/'.rawurlencode($id).'/pings'); + } + + /** + * Delete a hook. + * + * @link https://developer.github.com/v3/orgs/hooks/#delete-a-hook + * @param string $organization + * @param int $id + * @return null + */ + public function remove($organization, $id) + { + return $this->delete('orgs/'.rawurlencode($organization).'/hooks/'.rawurlencode($id)); + } +} diff --git a/test/Github/Tests/Api/Organization/HooksTest.php b/test/Github/Tests/Api/Organization/HooksTest.php new file mode 100644 index 00000000000..a3cdd4fcba4 --- /dev/null +++ b/test/Github/Tests/Api/Organization/HooksTest.php @@ -0,0 +1,156 @@ + 'hook')); + + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('get') + ->with('orgs/KnpLabs/hooks') + ->will($this->returnValue($expectedValue)); + + $this->assertEquals($expectedValue, $api->all('KnpLabs')); + } + + /** + * @test + */ + public function shouldShowHook() + { + $expectedValue = array('hook' => 'somename'); + + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('get') + ->with('orgs/KnpLabs/hooks/123') + ->will($this->returnValue($expectedValue)); + + $this->assertEquals($expectedValue, $api->show('KnpLabs', 123)); + } + + /** + * @test + */ + public function shouldRemoveHook() + { + $expectedValue = array('someOutput'); + + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('delete') + ->with('orgs/KnpLabs/hooks/123') + ->will($this->returnValue($expectedValue)); + + $this->assertEquals($expectedValue, $api->remove('KnpLabs', 123)); + } + + /** + * @test + * @expectedException \Github\Exception\MissingArgumentException + */ + public function shouldNotCreateHookWithoutName() + { + $data = array('config' => 'conf'); + + $api = $this->getApiMock(); + $api->expects($this->never()) + ->method('post'); + + $api->create('KnpLabs', $data); + } + + /** + * @test + * @expectedException \Github\Exception\MissingArgumentException + */ + public function shouldNotCreateHookWithoutConfig() + { + $data = array('name' => 'test'); + + $api = $this->getApiMock(); + $api->expects($this->never()) + ->method('post'); + + $api->create('KnpLabs', $data); + } + + /** + * @test + */ + public function shouldCreateHook() + { + $expectedValue = array('hook' => 'somename'); + $data = array('name' => 'test', 'config' => 'someconfig'); + + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('post') + ->with('orgs/KnpLabs/hooks', $data) + ->will($this->returnValue($expectedValue)); + + $this->assertEquals($expectedValue, $api->create('KnpLabs', $data)); + } + + /** + * @test + * @expectedException \Github\Exception\MissingArgumentException + */ + public function shouldNotUpdateHookWithoutConfig() + { + $data = array(); + + $api = $this->getApiMock(); + $api->expects($this->never()) + ->method('patch'); + + $api->update('KnpLabs', 123, $data); + } + + /** + * @test + */ + public function shouldUpdateHook() + { + $expectedValue = array('hook' => 'somename'); + $data = array('config' => 'config'); + + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('patch') + ->with('orgs/KnpLabs/hooks/123', $data) + ->will($this->returnValue($expectedValue)); + + $this->assertEquals($expectedValue, $api->update('KnpLabs', 123, $data)); + } + + /** + * @test + */ + public function shouldPingHook() + { + $expectedValue = null; + + $api = $this->getApiMock(); + $api->expects($this->once()) + ->method('post') + ->with('orgs/KnpLabs/hooks/123/pings') + ->will($this->returnValue($expectedValue)); + + $this->assertEquals($expectedValue, $api->ping('KnpLabs', 123)); + } + + protected function getApiClass() + { + return 'Github\Api\Organization\Hooks'; + } +}