Skip to content
PHP 5.6+ API Wrapper for The Movie Database
Branch: 2.1
Clone or download
Latest commit 92cbf43 Mar 1, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
build Fix phpdox xml namespace Sep 9, 2017
examples Add implementation for recommendations (#179) May 3, 2018
lib/Tmdb Fixes Y-d-m format Sep 1, 2018
.codeclimate.yml Adding codeclimate configuration. Jul 23, 2015
.editorconfig Add editorconfig Jul 24, 2017
.gitignore Adding credit_id Mar 4, 2014
.scrutinizer.yml Wrong indention in scrutinizer config Mar 8, 2015
.travis.yml Updating travis.yml Jan 20, 2018
LICENSE Initial base commit Nov 1, 2013 Fix faulty hhvm status badge Sep 9, 2017 Preparing 2.0 Jan 25, 2015
apikey.php.dist Implemented first citizen for GuestSession's, fixes #20 Apr 5, 2014
build.xml Adding a seperate build script to compile api docs and run coverage a… Feb 28, 2014
composer.json Allow Symfony 4 components (#172) Jan 20, 2018
phpunit.xml.dist Adding a seperate build script to compile api docs and run coverage a… Feb 28, 2014

A PHP Wrapper for use with the TMDB API.

License Build Status Code Coverage PHP & HHVM

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.


Latest Stable Version Latest Unstable Version Dependency Status Total Downloads

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

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


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.



Install Composer

$ curl -sS | 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);


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:

        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

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 ;))!

You can’t perform that action at this time.