Cleaning up some aspects of the API, as removing the TV\Network class…

… and moving it into it's first citizen class Network ( since TMDB added this ).

Also added travis support for php 5.6, and hhvm ( not officially supported though ).

.travis.yml

@@ -5,6 +5,8 @@ php:
   - 5.3
   - 5.4
   - 5.5
+  - 5.6
+  - hhvm
 
 before_script:
   - composer --prefer-source install

README.md

@@ -14,11 +14,18 @@ Stable
 
 [![Latest Stable Version](https://poser.pugx.org/wtfzdotnet/php-tmdb-api/v/stable.png)](https://packagist.org/packages/wtfzdotnet/php-tmdb-api)
 [![Dependency Status](https://www.versioneye.com/user/projects/530a7514ec137594df000010/badge.png)](https://www.versioneye.com/user/projects/530a7514ec137594df000010)
+[![Latest Unstable Version](https://poser.pugx.org/wtfzdotnet/php-tmdb-api/v/unstable.png)](https://packagist.org/packages/wtfzdotnet/php-tmdb-api)
 
-Unstable
-----------------
+First stable version is just around the corner, currently making a last thorough review and improving test coverage.
 
-[![Latest Unstable Version](https://poser.pugx.org/wtfzdotnet/php-tmdb-api/v/unstable.png)](https://packagist.org/packages/wtfzdotnet/php-tmdb-api)
+Currently unit tests are run on travis, with the following versions:
+
+- 5.3.3
+- 5.3
+- 5.4
+- 5.5
+- 5.6
+- hhvm _( we do not officially support this, however tests indicate it should be functional. )_
 
 Help & Donate
 --------------
@@ -68,6 +75,20 @@ Or if you prefer requests to happen securely:
 $client = new \Tmdb\Client($token, null, true);
 ```
 
+If you want to add some caching capabilities ( currently an implementation of the `GuzzleCachePlugin` );
+
+```php
+$client->setCaching(true, '/tmp/php-tmdb-api';
+```
+
+_This relies on max-age headers being sent back from TMDB, see the [documentation of the CachePlugin](http://guzzle.readthedocs.org/en/latest/plugins/cache-plugin.html)._
+
+If you want to add some logging capabilities ( currently an implementation of the `GuzzleLogPlugin`, requires `monolog/monolog`);
+
+```php
+$client->setLogging(true, '/tmp/php-tmdb-api.log';
+```
+
 Then we do some work on it:
 
 ```php
@@ -98,6 +119,20 @@ Or if you prefer requests to happen securely:
 $client = new \Tmdb\Client($token, null, true);
 ```
 
+If you want to add some caching capabilities ( currently an implementation of the `GuzzleCachePlugin` );
+
+```php
+$client->setCaching(true, '/tmp/php-tmdb-api';
+```
+
+_This relies on max-age headers being sent back from TMDB, see the [documentation of the CachePlugin](http://guzzle.readthedocs.org/en/latest/plugins/cache-plugin.html)._
+
+If you want to add some logging capabilities ( currently an implementation of the `GuzzleLogPlugin`, requires `monolog/monolog`);
+
+```php
+$client->setLogging(true, '/tmp/php-tmdb-api.log';
+```
+
 Then you pass this client onto one of the many repositories and do some work on it.
 
 ```php
@@ -148,5 +183,14 @@ $backdrop = $movie
     ->filterBackdrops()
 ;
 ```
+_And there are more Collections which provide filters, but you will find those out along the way._
+
+Some other useful hints
+-----------------------
+
+__There are 2 types of "main" collections, the `GenericCollection` and the `ResultCollection`.__
+
+The `GenericCollection holds any collection of objects ( e.g. an collection of movies ).
 
-__And there are more Collections which provide filters, but you will find those out along the way.__
+The `ResultCollection` is an extension of the `GenericCollection`, and inherits response parameters _( page, total_pages, total_results )_ from an resultset,
+this can be used to create paginators.

composer.json

@@ -19,10 +19,12 @@
     },
     "require-dev": {
         "phpunit/phpunit": ">=3.7",
-        "doctrine/cache": ">=1.3.0"
+        "doctrine/cache": ">=1.3.0",
+        "monolog/monolog": ">=1.7.0"
     },
     "suggest": {
-        "doctrine/cache": "This library is required if you want to make use of caching features."
+        "doctrine/cache": "This library is required if you want to make use of caching features.",
+        "monolog/monolog": "This library is required if you want to make use of logging features."
     },
     "autoload": {
         "psr-0": { "Tmdb\\": "lib/" }

examples/logging.php

@@ -0,0 +1,22 @@
+<?php
+/**
+ * This file is part of the Tmdb PHP API created by Michael Roterman.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @package Tmdb
+ * @author Michael Roterman <[email protected]>
+ * @copyright (c) 2013, Michael Roterman
+ * @version 0.0.1
+ */
+require_once '../vendor/autoload.php';
+require_once '../apikey.php';
+
+$token  = new \Tmdb\ApiToken(TMDB_API_KEY);
+$client = new \Tmdb\Client($token);
+
+$client->setLogging(true, '/www/dev/php-tmdb-api/api.log');
+
+$repository = new \Tmdb\Repository\MovieRepository($client);
+$movie      = $repository->load(19995);

lib/Tmdb/Api/Authentication.php

@@ -44,11 +44,13 @@ public function getNewToken()
      */
     public function authenticateRequestToken($token)
     {
+        //@codeCoverageIgnoreStart
         header(sprintf(
             'Location: %s/%s',
             self::REQUEST_TOKEN_URI,
             $token
         ));
+        //@codeCoverageIgnoreEnd
     }
 
     /**
@@ -63,10 +65,12 @@ public function getNewSession($requestToken)
     {
         try {
             return $this->get('authentication/session/new', array('request_token' => $requestToken));
+            //@codeCoverageIgnoreStart
         } catch (\Exception $e) {
             if ($e->getCode() == 401) {
                 throw new UnauthorizedRequestTokenException("The request token has not been validated yet.");
             }
+            //@codeCoverageIgnoreEnd
         }
     }
 

lib/Tmdb/ApiToken.php

@@ -11,6 +11,7 @@
  * @version 0.0.1
  */
 namespace Tmdb;
+use Tmdb\Exception\RuntimeException;
 
 /**
  * Class ApiToken
@@ -31,11 +32,16 @@ public function __construct($api_token = null)
     }
 
     /**
-     * @param  null  $apiToken
+     * @param  string           $apiToken
+     * @throws RuntimeException
      * @return $this
      */
     public function setToken($apiToken)
     {
+        if (!is_string($apiToken)) {
+            throw new RuntimeException('The Apitoken must be set.');
+        }
+
         $this->apiToken = $apiToken;
 
         return $this;

lib/Tmdb/Client.php

@@ -17,8 +17,12 @@
 use Guzzle\Common\HasDispatcherInterface;
 use Guzzle\Http\Client as GuzzleClient;
 use Guzzle\Http\ClientInterface;
+use Guzzle\Log\MessageFormatter;
+use Guzzle\Log\PsrLogAdapter;
+use Guzzle\Plugin\Backoff\BackoffPlugin;
 use Guzzle\Plugin\Cache\CachePlugin;
 use Guzzle\Plugin\Cache\DefaultCacheStorage;
+use Guzzle\Plugin\Log\LogPlugin;
 use Tmdb\HttpClient\HttpClient;
 use Tmdb\HttpClient\HttpClientInterface;
 use Tmdb\ApiToken as Token;
@@ -75,6 +79,25 @@ class Client
      */
     private $httpClient;
 
+    /**
+     * @var \Psr\Log\LoggerInterface
+     */
+    private $logger;
+
+    /**
+     * Holds the log path
+     *
+     * @var string
+     */
+    private $logPath;
+
+    /**
+     * Enable logging?
+     *
+     * @var bool
+     */
+    private $logEnabled = false;
+
     /**
      * Stores the cache path
      *
@@ -118,18 +141,22 @@ private function constructHttpClient(ClientInterface $httpClient = null)
             $acceptJsonHeaderPlugin = new AcceptJsonHeaderPlugin();
             $httpClient->addSubscriber($acceptJsonHeaderPlugin);
 
+            $backoffPlugin = BackoffPlugin::getExponentialBackoff(5);
+            $httpClient->addSubscriber($backoffPlugin);
+
             if ($this->getToken() instanceof ApiToken) {
                 $apiTokenPlugin = new ApiTokenPlugin($this->getToken());
                 $httpClient->addSubscriber($apiTokenPlugin);
             }
 
             if ($this->cacheEnabled && !empty($this->cachePath)) {
                 if (!class_exists('Doctrine\Common\Cache\FilesystemCache')) {
-                    /** @codeCoverageIgnoreStart */
+                    //@codeCoverageIgnoreStart
                     throw new RuntimeException(
-                        'Could not find the doctrine cache library, have you added doctrone-cache to your composer.json?'
+                        'Could not find the doctrine cache library,
+                        have you added doctrine-cache to your composer.json?'
                     );
-                    /** @codeCoverageIgnoreEnd */
+                    //@codeCoverageIgnoreEnd
                 }
 
                 $cachePlugin = new CachePlugin(array(
@@ -144,6 +171,35 @@ private function constructHttpClient(ClientInterface $httpClient = null)
                 $httpClient->addSubscriber($cachePlugin);
             }
 
+            if ($this->logEnabled && !empty($this->logPath)) {
+                if (empty($this->logger) && !class_exists('\Monolog\Logger')) {
+                    //@codeCoverageIgnoreStart
+                    throw new RuntimeException(
+                        'Could not find any logger set and the monolog logger library was not found
+                        to provide a default, you have to  set a custom logger on the client or
+                        have you forgot adding monolog to your composer.json?'
+                    );
+                    //@codeCoverageIgnoreEnd
+                } else {
+                    $this->setLogger(new \Monolog\Logger('php-tmdb-api'));
+                    $this->getLogger()->pushHandler(
+                        new \Monolog\Handler\StreamHandler(
+                            $this->logPath,
+                            \Monolog\Logger::DEBUG
+                        )
+                    );
+                }
+
+                if ($this->logger instanceof \Psr\Log\LoggerInterface) {
+                    $logPlugin = new LogPlugin(
+                        new PsrLogAdapter($this->logger),
+                        MessageFormatter::SHORT_FORMAT
+                    );
+
+                    $httpClient->addSubscriber($logPlugin);
+                }
+            }
+
             if ($this->getSessionToken() instanceof SessionToken) {
                 $sessionTokenPlugin = new SessionTokenPlugin($this->getSessionToken());
                 $httpClient->addSubscriber($sessionTokenPlugin);
@@ -433,7 +489,7 @@ public function getCacheEnabled()
     /**
      * Set cache path
      *
-     * You could simply pass an empty string to let the sys_get_temp_dir be used
+     * Leaving the second argument out will use sys_get_temp_dir()
      *
      * @param  boolean $enabled
      * @param  string  $path
@@ -460,4 +516,62 @@ public function getCachePath()
     {
         return $this->cachePath;
     }
+
+    /**
+     * @param  \Psr\Log\LoggerInterface $logger
+     * @return $this
+     */
+    public function setLogger($logger)
+    {
+        $this->logger = $logger;
+
+        return $this;
+    }
+
+    /**
+     * @return \Psr\Log\LoggerInterface
+     */
+    public function getLogger()
+    {
+        return $this->logger;
+    }
+
+    /**
+     * @return boolean
+     */
+    public function getLogEnabled()
+    {
+        return $this->logEnabled;
+    }
+
+    /**
+     * Set log path
+     *
+     * Leaving the second argument out will use sys_get_temp_dir()
+     *
+     * @param  boolean $enabled
+     * @param  string  $path
+     * @return $this
+     */
+    public function setLogging($enabled = true, $path = null)
+    {
+        $this->logEnabled = $enabled;
+        $this->logPath    = (null === $path) ?
+            sys_get_temp_dir() . '/php-tmdb-api.log' :
+            $path
+        ;
+
+        // @todo doesn't cover a custom client, would require un-registering all known plugins
+        $this->constructHttpClient();
+
+        return $this;
+    }
+
+    /**
+     * @return string
+     */
+    public function getLogPath()
+    {
+        return $this->logPath;
+    }
 }

lib/Tmdb/Model/Network.php

@@ -18,9 +18,23 @@
  */
 class Network extends AbstractModel
 {
+    /**
+     * @var integer
+     */
     private $id;
+
+    /**
+     * @var string
+     */
     private $name;
 
+    /**
+     * Properties that are available in the API
+     *
+     * These properties are hydrated by the ObjectHydrator, all the other properties are handled by the factory.
+     *
+     * @var array
+     */
     public static $properties = array(
         'id',
         'name',

lib/Tmdb/Model/Tv.php

@@ -19,7 +19,6 @@
 use Tmdb\Model\Image\BackdropImage;
 use Tmdb\Model\Image\PosterImage;
 use Tmdb\Model\Common\ExternalIds;
-use Tmdb\Model\Tv\Network;
 
 /**
  * Class Tv