yukoff / tmdb-api

PHP 5.6+ API Wrapper for The Movie Database

A PHP Wrapper for use with the TMDB API.

Inspired by php-github-api, php-gitlab-api and the Symfony Community.

If you have any questions or feature requests, please visit the google+ community.

Stable

Currently unit tests are run on travis, with the following versions:

• 5.6
• 7.0
• 7.1
• HHVM (failures allowed)
• nightly (failures allowed)

Features

Main features

• An complete integration of all the TMDB API has to offer (accounts, movies, tv etc. if something is missing I haven't added the updates yet!).
• Array implementation of the movie database (RAW)
• Model implementation of the movie database (By making use of the repositories)
• An ImageHelper class to help build image urls or html elements.

Other things worth mentioning

• Retry subscriber enabled by default to handle any rate limit errors.
• Caching subscriber enabled by default, based on max-age headers returned by TMDB, requires doctrine-cache.
• Logging subscriber and is optional, requires monolog. Could prove useful during development.

Plug-ins

• Symfony
  • php-tmdb/symfony.
• Laravel
  • php-tmdb/laravel.

Installation

Install Composer

$ curl -sS https://getcomposer.org/installer | php
$ sudo mv composer.phar /usr/local/bin/composer

You are not obliged to move the composer.phar file to your /usr/local/bin, it is however considered easy to have an global installation.

Add the following to your require block in composer.json config

"php-tmdb/api": "~2.1"

If your new to composer and have no clue what I'm talking about

Just create a file named composer.json in your document root:

{
    "require": {
        "php-tmdb/api": "~2.1"
    }
}

Now let's install and pull in the dependencies!

composer install

Include Composer's autoloader:

require_once dirname(__DIR__).'/vendor/autoload.php';

To use the examples provided, copy the apikey.php.dist to apikey.php and change the settings.

Constructing the Client

First we always have to construct the client:

$token  = new \Tmdb\ApiToken('your_tmdb_api_key_here');
$client = new \Tmdb\Client($token);

If you'd like to make unsecure requests (by default we use secure requests).

$client = new \Tmdb\Client($token, ['secure' => false]);

Caching is enabled by default, and uses a slow filesystem handler, which you can either:

• Replace the path of the storage of, by supplying the option in the client:

$client = new \Tmdb\Client($token, [
    'cache' => [
        'path' => '/tmp/php-tmdb'
    ]
]);

• Or replace the whole implementation with another CacheStorage of Doctrine:

use Doctrine\Common\Cache\ArrayCache;

$client = new \Tmdb\Client($token, [
        'cache' => [
            'handler' => new ArrayCache()
        ]
    ]
);

This will only keep cache in memory during the length of the request, see the documentation of Doctrine Cache for the available adapters.

Strongly against this, disabling cache:

$client = new \Tmdb\Client($token, [
    'cache' => [
        'enabled' => false
    ]
]);

If you want to add some logging capabilities (requires monolog/monolog), defaulting to the filesystem;

$client = new \Tmdb\Client($token, [
    'log' => [
        'enabled' => true,
        'path'    => '/var/www/php-tmdb-api.log'
    ]
]);

However during development you might like some console magic like ChromePHP or FirePHP;

$client = new \Tmdb\Client($token, [
    'log' => [
        'enabled' => true,
        'handler' => new \Monolog\Handler\ChromePHPHandler()
    ]
]);

General API Usage

If your looking for a simple array entry point the API namespace is the place to be.

$movie = $client->getMoviesApi()->getMovie(550);

If you want to provide any other query arguments.

$movie = $client->getMoviesApi()->getMovie(550, array('language' => 'en'));

Model Usage

However the library can also be used in an object oriented manner, which I reckon is the preferred way of doing things.

Instead of calling upon the client, you pass the client onto one of the many repositories and do then some work on it.

$repository = new \Tmdb\Repository\MovieRepository($client);
$movie      = $repository->load(87421);

echo $movie->getTitle();

The repositories also contain the other API methods that are available through the API namespace.

$repository = new \Tmdb\Repository\MovieRepository($client);
$topRated = $repository->getTopRated(array('page' => 3));
// or
$popular = $repository->getPopular();

Some other useful hints

Event Dispatching

Since 2.0 requests are handled by the EventDispatcher, which gives you before and after hooks, the before hook allows an event to stop propagation for the request event, meaning you are able to stop the main request from happening, you will have to set a Response object in that event though.

See the files for TmdbEvents and RequestSubscriber respectively.

Image Helper

An ImageHelper class is provided to take care of the images, which does require the configuration to be loaded:

$configRepository = new \Tmdb\Repository\ConfigurationRepository($client);
$config = $configRepository->load();

$imageHelper = new \Tmdb\Helper\ImageHelper($config);

echo $imageHelper->getHtml($image, 'w154', 154, 80);

Plug-ins

At the moment there are only two useful plug-ins that are not enabled by default, and you might want to use these:

$plugin = new \Tmdb\HttpClient\Plugin\LanguageFilterPlugin('nl');

Tries to fetch everything it can in Dutch.

$plugin = new \Tmdb\HttpClient\Plugin\AdultFilterPlugin(true);

We like naughty results, if configured this way, provide false to filter these out.

Collection Filtering

We also provide some easy methods to filter any collection, you should note however you can always implement your own filter easily by using Closures:

foreach($movie->getImages()->filter(
        function($key, $value){
            if ($value instanceof \Tmdb\Model\Image\PosterImage) { return true; }
        }
    ) as $image) {

    // do something with all poster images
}

These basic filters however are already covered in the Images collection object:

$backdrop = $movie
    ->getImages()
    ->filterBackdrops()
;

And there are more Collections which provide filters, but you will find those out along the way.

The GenericCollection and the ResultCollection

The GenericCollection holds any collection of objects (e.g. an collection of movies).

The ResultCollection is an extension of the GenericCollection, and inherits the response parameters (page, total_pages, total_results) from an result set, this can be used to create paginators.

Help & Donate

If you use this in a project whether personal or business, I'd like to know where it is being used, so please drop me an e-mail! :-)

If this project saved you a bunch of work, or you just simply appreciate my efforts, please consider donating a beer (or two ;))!