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,55 @@ 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()->getList( 'ornicar' );
+```
+
+Returns a list of user’s gists.
+
+#### Get a single gist
+
+```php
+    $gist = $github->getGistApi()->getGist( 1 );
+```
+
+Returns a single gist.
+
+#### Create a gist
+
+```php
+    $gist = $github->getGistApi()->create( 'filename.php', 'file contents', 'This is an optional description of my gist', true );
+```
+
+Creates and returns a public gist.
+
+#### Update a gist
+
+```php
+    $description = 'This is a new description of my gist';
+    $files = array( 'new_file.txt' => array( 'content' => 'a new file' ));
+    $gist = $github->getGistApi()->update( 1234, array( 'description' => $description, 'files' => $files ));
+```
+
+Updates and returns my gist with id 1234.
+
+#### Delete a gist
+
+```php
+    $gist = $github->getGistApi()->remove( 1234 );
+```
+
+Delete my gist with id 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 +817,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,87 @@
+<?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 gists by username
+     * @link http://developer.github.com/v3/gists/
+     * 
+     * @param   string  $username    the username
+     * @return  array                list of gist found 
+     */
+    public function getList($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.
+     * @link http://developer.github.com/v3/gists/
+     *
+     * @param   string  $description      gist description
+     * @param   bool    $public           1 for public, 0 for private
+     * @param   string  $filename         gist filename
+     * @param   string  $content          gist file contents
+     * @return  array                     returns gist data
+     */
+    public function create($filename, $content, $description = '', $public = false)
+    {
+        $input = array(
+            'description' => $description,
+            'public' => $public,
+            'files' => array(
+                $filename => array(
+                    'content' => $content
+                )
+            )
+        );
+
+        return $this->post('gists', $input);
+    }  
+
+    /**
+     * Edit a gist
+     * @link http://developer.github.com/v3/gists/
+     *
+     * @param   string  $$id              the gist id
+     * @param   array   $values           the key => value pairs to post
+     * @return  array                     informations about the gist
+     */
+    public function update($id, $values)
+    {
+        return $this->patch('gists/'.urlencode($id), $values);
+    }    
+
+    /**
+     * Remove a gist by id
+     * @link http://developer.github.com/v3/gists/
+     * 
+     * @param   int  $id          the gist id
+     * @return  null              
+     */
+    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,81 @@
+<?php
+
+namespace Github\Tests\Api;
+
+use Github\Tests\ApiTestCase;
+
+class GistTest extends ApiTestCase
+{
+    /**
+     * @test
+     */
+    public function shouldCreateGist()
+    {
+        $api = $this->getApiMock();
+
+        $input = array(
+            'description' => '',
+            'public' => false,
+            'files' => array(
+                'filename.txt' => array(
+                    'content' => 'content'
+                )
+            )
+        );
+
+        $filename = 'filename.txt';
+        $content = 'content';
+
+        $api->expects($this->once())
+            ->method('post')
+            ->with('gists', $input);
+
+        $gist = $api->create($filename, $content);
+    }
+
+    /**
+     * @test
+     */
+    public function shouldUpdateGist()
+    {
+        $api = $this->getApiMock();
+
+        $input = array(
+            'description' => '',
+            'files' => array(
+                'filename.txt' => array(
+                    'filename' => 'new_name.txt',
+                    'content'  => 'content'
+                ),
+                'filename_new.txt' => array(
+                    'content'  => 'content new'
+                )
+            )
+        );
+
+        $api->expects($this->once())
+            ->method('patch')
+            ->with('gists/5', $input);
+
+        $gist = $api->update(5, $input);
+    }    
+
+    /**
+     * @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';
+    }    
+}

test/Github/Tests/Functional/GistTest.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace Github\Tests\Functional;
+
+use Github\Client;
+
+class GistTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @test
+     */
+    public function shouldRetrieveGistsListByUser()
+    {
+        $username = 'KnpLabs';
+
+        $github = new Client();
+        $gists = $github->getGistApi()->getList($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 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']);        
+    }    
+}