Gists API

README.markdown

@@ -50,7 +50,7 @@ From this object, you can access to all GitHub apis, listed below.
 <a name='nav'></a>
 ## 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][]
 
 <a name='users'></a>
 ## Users
@@ -556,8 +556,6 @@ To include non GitHub users, add a third parameter to true:
 ```
 
 
-
-
 <a name='pull_requests'></a>
 ## Pull Requests
 <a href='#nav' alt='Back to the navigation'>Go back to the Navigation</a>
@@ -629,6 +627,97 @@ Requires authentication. The issue ID is provided instead of title and body.
 This returns the details of the pull request.
 
 
+<a name='gists'></a>
+## Gists
+<a href='#nav' alt='Back to the navigation'>Go back to the Navigation</a>
+
+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 );
+```
+
+
 <a name='request_any_route'></a>
 ## Request any Route
 <a href='#nav' alt='Back to the navigation'>Go back to the Navigation</a>
@@ -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

lib/Github/Api/Gist.php

@@ -0,0 +1,120 @@
+<?php
+
+namespace Github\Api;
+
+/**
+ * Creating, editing, deleting and listing gists
+ *
+ * @link      http://developer.github.com/v3/gists/
+ * @author    Edoardo Rivello <edoardo.rivello at gmail dot com>
+ * @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));
+    }    
+}

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

test/Github/Tests/Api/GistTest.php

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