diff --git a/README.markdown b/README.markdown index 9adf5050173..212a8fdf385 100755 --- a/README.markdown +++ b/README.markdown @@ -50,7 +50,7 @@ From this object, you can access to all GitHub apis, listed below. ## Navigation -[Users][] | [Issues][] | [Commits][] | [Objects][] | [Repos][] | [Pull Requests][] | [Request any Route][] | [Authentication & Security][] | [Customize php-github-api][] | [Run Test Suite][] +[Users][] | [Issues][] | [Commits][] | [Objects][] | [Repos][] | [Pull Requests][] | [Gists][] | [Request any Route][] | [Authentication & Security][] | [Customize php-github-api][] | [Run Test Suite][] ## Users @@ -556,8 +556,6 @@ To include non GitHub users, add a third parameter to true: ``` - - ## Pull Requests Go back to the Navigation @@ -629,6 +627,97 @@ Requires authentication. The issue ID is provided instead of title and body. This returns the details of the pull request. + +## Gists +Go back to the Navigation + +Creating, editing, deleting and listing gists. Wraps [GitHub Gists API](http://developer.github.com/v3/gists/). + +#### List gists of a specific user + +```php + $gists = $github->getGistApi()->getListByUser( 'ornicar' ); +``` + +#### List all public gists. + +```php + $gists = $github->getGistApi()->getPublicList(); +``` + +#### List the authenticated user’s starred gists. + +```php + $gists = $github->getGistApi()->getStarredList(); +``` + +Requires authentication. + +#### List the authenticated user’s gists or if called anonymously, this will return all public gists. + +```php + $gists = $github->getGistApi()->getList(); +``` + +#### Get a single gist + +```php + $gist = $github->getGistApi()->getGist( 1 ); +``` + +#### Create a gist + +```php + $files = array( 'filename.txt' => array( 'content' => 'txt file content' )); + $gist = $github->getGistApi()->create( $files, true, 'This is an optional description' ); +``` + +Creates and returns a public gist. + +#### Update a gist + +You can update ``description``. + +```php + $files = array(); + $gist = $github->getGistApi()->update( 1234, $files, 'This is a new description' ); +``` + +You can update ``content`` of a previous file's version. + +```php + $files = array( 'filename.txt' => array( 'content' => 'updated txt file content' )); + $gist = $github->getGistApi()->update( 1234, $files ); +``` + +You can update the ``filename`` of a previous file's version. + +```php + $files = array( 'filename.txt' => array( 'filename' => 'new-filename.txt' )); + $gist = $github->getGistApi()->update( 1234, $files ); +``` + +You can add a new file to the gist. + +```php + $files = array( 'new-filename.php' => array( 'content' => 'a new file content' )); + $gist = $github->getGistApi()->update( 1234, $files ); +``` + +You can remove a file from the gist. + +```php + $files = array( 'filename.txt' => null ); + $gist = $github->getGistApi()->update( 1234, $files ); +``` + +#### Delete a gist + +```php + $gist = $github->getGistApi()->remove( 1234 ); +``` + + ## Request any Route Go back to the Navigation @@ -770,6 +859,7 @@ Thanks to GitHub for the high quality API and documentation. [Commits]: #commits [Objects]: #objects [Repos]: #repos +[Gists]: #gists [Pull Requests]: #pull_requests [Request any Route]: #request_any_route [Authentication & Security]: #authentication_and_security diff --git a/lib/Github/Api/Gist.php b/lib/Github/Api/Gist.php new file mode 100644 index 00000000000..c9f7a0b0a9d --- /dev/null +++ b/lib/Github/Api/Gist.php @@ -0,0 +1,120 @@ + + * @license MIT License + */ +class Gist extends Api +{ + /** + * List the authenticated user’s gists or if called anonymously, + * this will return all public gists. + * @link http://developer.github.com/v3/gists/ + * + * @return array list of gist found + */ + public function getList() + { + return $this->get('gists'); + } + + /** + * List all public gists. + * @link http://developer.github.com/v3/gists/ + * + * @return array list of gist found + */ + public function getPublicList() + { + return $this->get('gists/public'); + } + + /** + * List the authenticated user’s starred gists. Requires authentication. + * @link http://developer.github.com/v3/gists/ + * + * @return array list of gist found + */ + public function getStarredList() + { + return $this->get('gists/starred'); + } + + /** + * List gists by username. + * @link http://developer.github.com/v3/gists/ + * + * @param string $username the username + * @return array list of gist found + */ + public function getListByUser($username) + { + return $this->get('users/'.urlencode($username).'/gists'); + } + + /** + * Show a specific gist. + * @link http://developer.github.com/v3/gists/ + * + * @param string $id the gist id + * @return array data from gist + */ + public function getGist($id) + { + return $this->get('gists/'.urlencode($id)); + } + + /** + * Create a new gist for the authenticated user otherwise for an + * anonymous user. + * + * @link http://developer.github.com/v3/gists/ + * + * @param array $files files that make up this gist + * @param bool $public 1 for public, 0 for private + * @param string $description optional gist description + * @return array returns gist data + */ + public function create($files, $public = false, $description = '') + { + return $this->post('gists', array( + 'description' => $description, + 'public' => $public, + 'files' => $files + )); + } + + /** + * Edit a gist. + * @link http://developer.github.com/v3/gists/ + * + * @param string $id the gist id + * @param array $files files that make up this gist + * @param string $description optional gist description + * @return array informations about the gist + */ + public function update($id, array $files = array(), $description = '') + { + return $this->patch('gists/'.urlencode($id), array( + 'description' => $description, + 'files' => $files + )); + } + + /** + * Remove a gist by id. + * @link http://developer.github.com/v3/gists/ + * + * @param int $id the gist id + * @return Response + */ + public function remove($id) + { + return $this->delete('gists/'.urlencode($id)); + } +} diff --git a/lib/Github/Client.php b/lib/Github/Client.php index adf4aa4caad..3d8e58fb23d 100644 --- a/lib/Github/Client.php +++ b/lib/Github/Client.php @@ -224,6 +224,20 @@ public function getCommitApi() return $this->apis['commit']; } + + /** + * Get the gist API + * + * @return Api\Gist the gist API + */ + public function getGistApi() + { + if (!isset($this->apis['gist'])) { + $this->apis['gist'] = new Api\Gist($this); + } + + return $this->apis['gist']; + } /** * Get the repo API diff --git a/test/Github/Tests/Api/GistTest.php b/test/Github/Tests/Api/GistTest.php new file mode 100644 index 00000000000..f82b7e164fd --- /dev/null +++ b/test/Github/Tests/Api/GistTest.php @@ -0,0 +1,96 @@ +getApiMock(); + + $api->expects($this->once()) + ->method('get') + ->with('gists/starred'); + + $gists = $api->getStarredList(); + } + + /** + * @test + */ + public function shouldCreateAnonymousGist() + { + $api = $this->getApiMock(); + + $files = array( + 'filename.txt' => array( + 'content' => 'content' + ) + ); + + $input = array( + 'description' => '', + 'public' => false, + 'files' => $files + ); + + $api->expects($this->once()) + ->method('post') + ->with('gists', $input); + + $gist = $api->create($files); + } + + /** + * @test + */ + public function shouldUpdateGist() + { + $api = $this->getApiMock(); + + $files = array( + 'filename.txt' => array( + 'filename' => 'new_name.txt', + 'content' => 'content' + ), + 'filename_new.txt' => array( + 'content' => 'content new' + ) + ); + + $input = array( + 'description' => 'jimbo', + 'files' => $files + ); + + $api->expects($this->once()) + ->method('patch') + ->with('gists/5', $input); + + $gist = $api->update(5, $files, 'jimbo'); + } + + /** + * @test + */ + public function shouldDeleteGist() + { + $api = $this->getApiMock(); + + $api->expects($this->once()) + ->method('delete') + ->with('gists/5'); + + $api->remove(5); + } + + protected function getApiClass() + { + return 'Github\Api\Gist'; + } +} diff --git a/test/Github/Tests/Functional/GistTest.php b/test/Github/Tests/Functional/GistTest.php new file mode 100644 index 00000000000..9542600f409 --- /dev/null +++ b/test/Github/Tests/Functional/GistTest.php @@ -0,0 +1,93 @@ +getGistApi()->getList(); + $gist = array_pop($gists); + + $this->assertArrayHasKey('url', $gist); + $this->assertArrayHasKey('files', $gist); + $this->assertArrayHasKey('comments', $gist); + $this->assertArrayHasKey('created_at', $gist); + $this->assertArrayHasKey('updated_at', $gist); + $this->assertArrayHasKey('user', $gist); + } + + /** + * @test + */ + public function shouldNotGetStarredListWithoutAuthorization() + { + $github = new Client(); + $response = $github->getGistApi()->getStarredList(); + + $this->assertEquals('Requires authentication', $response['message']); + } + + /** + * @test + */ + public function shouldRetrieveGistsListByUser() + { + $username = 'KnpLabs'; + + $github = new Client(); + $gists = $github->getGistApi()->getListByUser($username); + $gist = array_pop($gists); + + $this->assertArrayHasKey('url', $gist); + $this->assertArrayHasKey('files', $gist); + $this->assertArrayHasKey('comments', $gist); + $this->assertArrayHasKey('created_at', $gist); + $this->assertArrayHasKey('updated_at', $gist); + $this->assertArrayHasKey('user', $gist); + $this->assertEquals('KnpLabs', $gist['user']['login']); + } + + /** + * @test + */ + public function shouldRetrievePublicGistsList() + { + $github = new Client(); + $gists = $github->getGistApi()->getPublicList(); + $gist = array_pop($gists); + + $this->assertArrayHasKey('url', $gist); + $this->assertArrayHasKey('files', $gist); + $this->assertArrayHasKey('comments', $gist); + $this->assertArrayHasKey('created_at', $gist); + $this->assertArrayHasKey('updated_at', $gist); + $this->assertArrayHasKey('user', $gist); + } + + /** + * @test + */ + public function shouldRetrieveGistById() + { + $id = 1; + + $github = new Client(); + $gist = $github->getGistApi()->getGist($id); + + $this->assertArrayHasKey('url', $gist); + $this->assertArrayHasKey('files', $gist); + $this->assertArrayHasKey('comments', $gist); + $this->assertArrayHasKey('created_at', $gist); + $this->assertArrayHasKey('updated_at', $gist); + $this->assertArrayHasKey('user', $gist); + $this->assertArrayHasKey('gistfile1.txt', $gist['files']); + $this->assertEquals('schacon', $gist['user']['login']); + } +}