Use If-modified-since headers to avoid X-Rate-Limit decrease

README.markdown

@@ -58,6 +58,21 @@ $repositories = $client->api('user')->repositories('ornicar');
 
 From `$client` object, you can access to all GitHub.
 
+## Cache usage
+
+```php
+<?php
+
+// This file is generated by Composer
+require_once 'vendor/autoload.php';
+
+$client = new Github\Client(new CachedHttpClient(new FilesystemCache('/tmp/github-api-cache')));
+```
+
+Using cache, the client will get cached responses if resources haven't changed since last time,  
+**without** reaching the `X-Rate-Limit` [imposed by github](http://developer.github.com/v3/#rate-limiting).
+
+
 ## Documentation
 
 See the `doc` directory for more detailed documentation.

lib/Github/Client.php

@@ -67,15 +67,11 @@ class Client
     /**
      * Instantiate a new GitHub client
      *
-     * @param null|ClientInterface $httpClient Buzz client
+     * @param null|HttpClientInterface $httpClient Github http client
      */
-    public function __construct(ClientInterface $httpClient = null)
+    public function __construct(HttpClientInterface $httpClient = null)
     {
-        $httpClient = $httpClient ?: new Curl();
-        $httpClient->setTimeout($this->options['timeout']);
-        $httpClient->setVerifyPeer(false);
-
-        $this->httpClient = new HttpClient($this->options, $httpClient);
+        $this->httpClient = $httpClient ?: new HttpClient($this->options);
     }
 
     /**

lib/Github/HttpClient/Cache/CacheInterface.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Github\HttpClient\Cache;
+
+use Github\HttpClient\Message\Response;
+
+/**
+ * Caches github api responses
+ *
+ * @author     Florian Klein <florian.klein@free.fr>
+ */
+interface CacheInterface
+{
+    /**
+     * @param  string the id of the cached resource
+     * @return int the modified since timestamp
+     **/
+    public function getModifiedSince($id);
+
+    /**
+     * @param  string the id of the cached resource
+     * @return Response The cached response object
+     **/
+    public function get($id);
+
+    /**
+     * @param string the id of the cached resource
+     * @param Response the response to cache
+     **/
+    public function set($id, Response $response);
+}
+

lib/Github/HttpClient/Cache/FilesystemCache.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace Github\HttpClient\Cache;
+
+use Github\HttpClient\Message\Response;
+
+class FilesystemCache implements CacheInterface
+{
+    protected $path;
+
+    public function __construct($path = null)
+    {
+        $this->path = $path ?: sys_get_temp_dir().DIRECTORY_SEPARATOR.'php-github-api-cache';
+    }
+
+    public function get($id)
+    {
+        if (false !== $content = @file_get_contents($this->getPath($id))) {
+            return unserialize($content);
+        }
+
+        throw new \InvalidArgumentException(sprintf('File "%s" not found', $this->getPath($id)));
+    }
+
+    public function set($id, Response $response)
+    {
+        if (!is_dir($this->path)) {
+            mkdir($this->path, 0777, true);
+        }
+
+        if (false === $bytes = @file_put_contents($this->getPath($id), serialize($response))) {
+            throw new \InvalidArgumentException(sprintf('Cannot put content in file "%s"', $this->getPath($id)));
+        }
+    }
+
+    public function getModifiedSince($id)
+    {
+        if (file_exists($this->getPath($id))) {
+            return filemtime($this->getPath($id));
+        }
+    }
+
+    protected function getPath($id)
+    {
+        return sprintf('%s%s%s', rtrim($this->path, DIRECTORY_SEPARATOR), DIRECTORY_SEPARATOR, md5($id));
+    }
+}
+

lib/Github/HttpClient/CachedHttpClient.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace Github\HttpClient;
+
+use Buzz\Client\ClientInterface;
+use Buzz\Message\MessageInterface;
+use Buzz\Message\RequestInterface;
+use Buzz\Listener\ListenerInterface;
+
+use Github\Exception\ErrorException;
+use Github\Exception\RuntimeException;
+use Github\HttpClient\Listener\ErrorListener;
+use Github\HttpClient\Message\Request;
+use Github\HttpClient\Message\Response;
+use Github\HttpClient\Cache\CacheInterface;
+use Github\HttpClient\Cache\FilesystemCache;
+
+/**
+ * Performs requests on GitHub API using If-Modified-Since headers.
+ * Returns a cached version if not modified
+ * Avoids increasing the X-Rate-Limit, which is cool
+ *
+ * @author Florian Klein <florian.klein@free.fr>
+ */
+class CachedHttpClient extends HttpClient
+{
+    protected $cache;
+
+    public function __construct(array $options = array(), ClientInterface $client = null, CacheInterface $cache = null)
+    {
+        parent::__construct($options, $client);
+
+        $this->cache = $cache ?: new FilesystemCache;
+    }
+
+    public function request($path, array $parameters = array(), $httpMethod = 'GET', array $headers = array(), Response $response = null)
+    {
+        $response = parent::request($path, $parameters, $httpMethod, $headers, $response);
+
+        $key = trim($this->options['base_url'].$path, '/');
+        if ($response->isNotModified()) {
+            return $this->cache->get($key);
+        }
+
+        $this->cache->set($key, $response);
+
+        return $response;
+    }
+
+    /**
+     * Create requests with If-Modified-Since headers
+     * @param string $httpMethod
+     * @param string $url
+     *
+     * @return Request
+     */
+    protected function createRequest($httpMethod, $url)
+    {
+        $request = parent::createRequest($httpMethod, $url);
+        $modifiedSince = date('r', $this->cache->getModifiedSince($url));
+        $request->addHeader(sprintf('If-Modified-Since: %s', $modifiedSince));
+
+        return $request;
+    }
+}

lib/Github/HttpClient/HttpClient.php

@@ -12,6 +12,7 @@
 use Github\HttpClient\Listener\ErrorListener;
 use Github\HttpClient\Message\Request;
 use Github\HttpClient\Message\Response;
+use Buzz\Client\Curl;
 
 /**
  * Performs requests on GitHub API. API documentation should be self-explanatory.
@@ -48,8 +49,12 @@ class HttpClient implements HttpClientInterface
      * @param array           $options
      * @param ClientInterface $client
      */
-    public function __construct(array $options, ClientInterface $client)
+    public function __construct(array $options = array(), ClientInterface $client = null)
     {
+        $client = $client ?: new Curl();
+        $client->setTimeout($this->options['timeout']);
+        $client->setVerifyPeer(false);
+
         $this->options = array_merge($this->options, $options);
         $this->client  = $client;
 
@@ -139,7 +144,7 @@ public function put($path, array $parameters = array(), array $headers = array()
     /**
      * {@inheritDoc}
      */
-    public function request($path, array $parameters = array(), $httpMethod = 'GET', array $headers = array())
+    public function request($path, array $parameters = array(), $httpMethod = 'GET', array $headers = array(), Response $response = null)
     {
         $path = trim($this->options['base_url'].$path, '/');
 
@@ -154,7 +159,9 @@ public function request($path, array $parameters = array(), $httpMethod = 'GET',
             }
         }
 
-        $response = new Response();
+        if (null === $response) {
+            $response = new Response;
+        }
 
         try {
             $this->client->send($request, $response);
@@ -198,7 +205,7 @@ public function getLastResponse()
      *
      * @return Request
      */
-    private function createRequest($httpMethod, $url)
+    protected function createRequest($httpMethod, $url)
     {
         $request = new Request($httpMethod);
         $request->setHeaders($this->headers);

lib/Github/HttpClient/HttpClientInterface.php

@@ -3,6 +3,7 @@
 namespace Github\HttpClient;
 
 use Github\Exception\InvalidArgumentException;
+use Github\HttpClient\Message\Response;
 
 /**
  * Performs requests on GitHub API. API documentation should be self-explanatory.
@@ -77,7 +78,7 @@ public function delete($path, array $parameters = array(), array $headers = arra
      *
      * @return array              Data
      */
-    public function request($path, array $parameters = array(), $httpMethod = 'GET', array $headers = array());
+    public function request($path, array $parameters = array(), $httpMethod = 'GET', array $headers = array(), Response $response = null);
 
     /**
      * Change an option value.

lib/Github/HttpClient/Message/Response.php

@@ -64,4 +64,14 @@ public function getApiLimit()
             throw new ApiLimitExceedException($this->options['api_limit']);
         }
     }
+
+    /**
+     * Is not modified
+     *
+     * @return Boolean
+     */
+    public function isNotModified()
+    {
+        return 304 === $this->getStatusCode();
+    }
 }

test/Github/Tests/Api/AbstractApiTest.php

@@ -126,7 +126,7 @@ protected function getAbstractApiObject($client)
      */
     protected function getClientMock()
     {
-        return new \Github\Client($this->getHttpClientMock());
+        return new \Github\Client($this->getHttpMock());
     }
 
     /**

test/Github/Tests/Api/TestCase.php

@@ -23,7 +23,7 @@ protected function getApiMock()
 
         $mock = $this->getMock('Github\HttpClient\HttpClient', array(), array(array(), $httpClient));
 
-        $client = new \Github\Client($httpClient);
+        $client = new \Github\Client($mock);
         $client->setHttpClient($mock);
 
         return $this->getMockBuilder($this->getApiClass())

test/Github/Tests/HttpClient/Cache/FilesystemCacheTest.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Github\Tests\HttpClient\Cache;
+
+use Github\HttpClient\Message\Response;
+use Github\HttpClient\Cache\FilesystemCache;
+
+class FilesystemCacheTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @test
+     */
+    public function shouldStoreAResponseForAGivenKey()
+    {
+        $cache = new FilesystemCache('/tmp/github-api-test');
+
+        $cache->set('test', new Response);
+
+        $this->assertNotNull($cache->get('test'));
+    }
+
+    /**
+     * @test
+     */
+    public function shouldGetATimestampForExistingFile()
+    {
+        $cache = new FilesystemCache('/tmp/github-api-test');
+
+        $cache->set('test', new Response);
+
+        $this->assertInternalType('int', $cache->getModifiedSince('test'));
+    }
+
+    /**
+     * @test
+     */
+    public function shouldNotGetATimestampForInexistingFile()
+    {
+        $cache = new FilesystemCache('/tmp/github-api-test');
+
+        $this->assertNull($cache->getModifiedSince('test2'));
+    }
+}
+