vfalies/tmdb

A PHP Wrapper for The Internet Movie Database API

1.12 2021-08-20 14:17 UTC

Requires

• php: >= 7.1
• guzzlehttp/guzzle: >= 6.3
• psr/log: ~1.1.3

Requires (Dev)

• friendsofphp/php-cs-fixer: >=2.15.3
• monolog/monolog: >1.25.1
• phpunit/phpunit: >=7.0 <9.5.4

Suggests

• monolog/monolog: Allows more advanced logging of the application flow

MIT

• Vincent Faliès

README

Tmdb is a PHP wrapper for The Movie Database API V3.

Table of contents

1. Features
2. Installation
3. Basic usage
4. Usage
   1. Getting a TMDB instance
   2. Movie
   3. TV Show
   4. Collection
   5. People
   6. Company
   7. Find by an external ID
   8. Authentication
   9. Media Helper
5. Unit tests
6. About

Features

Features actualy supported :

• Search
  • Movie
  • TV Show
  • Collection
  • Company
• Getting informations
  • Movie
  • TV Show
  • Collection
  • Company
  • Genres
  • TV Network
• Account
  • Authentification
  • Movies / TV Shows rating
  • Movies / TV Shows favorites
  • Movies / TV Shows watchlist
• Media
• Genres
• Jobs
• Find
  • IMDb
  • TheTVDb
  • TVRage
  • Facebook
  • Twitter
  • Instagram

Installation

Requirements

• Tmdb works with PHP 7.1 and higher
• TheMovieDatabase API key

Composer

Install the lastest version with

$ composer require vfalies/tmdb

Basic Usage

<?php

require 'vendor/autoload.php';

use VfacTmdb\Factory;
use VfacTmdb\Search;
use VfacTmdb\Item;

// Initialize Wrapper
$tmdb = Factory::create()->getTmdb('your_api_key');

// Search a movie
$search    = new Search($tmdb);
$responses = $search->movie('star wars');

// Get all results
foreach ($responses as $response)
{
    echo $response->getTitle();
}

// Get movie information
$item  = new Item($tmdb);
$infos = $item->getMovie(11, array('language' => 'fr-FR'));

echo $infos->getTitle();

Usage

Getting a TMDB instance

TMDB is the main class of the library. It has two dependencies :

• a API key from The Movie DataBase website
• a Psr\Log\LoggerInterface instance to write logs

Using the Factory

It is the easiest way to load TMDB

<?php
require 'vendor/autoload.php';

use VfacTmdb\Factory;

$tmdb = Factory::create()->getTmdb('your_api_key');

In a Slim application

If your application is built with Slim, you can add TMDB in your dependencies and inject Slim's Monolog instance into it. Just add this in dependencies.php

$container['tmdb'] = function ($c) {
    $api_key = $c->get('settings')['tmdb']['api_key'];
    $tmdb = new \vfalies\tmdb\Tmdb($api_key, $c->logger);
}

In this example, API key is declared in settings.php

return [
    'settings' = [
        'tmdb' = [
            'api_key' = 'your_api_key';
        ]
    ]
];

Do it yourself

Convenient if you need too inject your own dependencies. In the example below, we inject Monolog configured to write logs on standards output.

<?php
require 'vendor/autoload.php';

use VfacTmdb\Tmdb;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('default', [new StreamHandler('php://stdout')])

$tmdb = Tmdb('your_api_key', $logger);

Movie

Search a movie

$search    = new Search($tmdb);
$responses = $search->movie('star wars');

The search returns Generator object of Result\Movie object.

See demo

Get a movie

$item  = new Item($tmdb);
$movie = $item->getMovie($movie_id);

echo $movie->getTitle();

The getter returns a Movie object.

See demo

TV Show

Search a TV Show

$search    = new Search($tmdb);
$responses = $search->tvshow('game of thrones');

The search returns Generator object of Result\TVShow object.

See demo

Get a TV Show

$item   = new Item($tmdb);
$tvshow = $item->getTVShow($tvshow_id);

echo $tvshow->getTitle();

The getter returns a TVShow object.

See demo

Get a TV Season

$item     = new Item($tmdb);
$tvseason = $item->getTVSeason($tvshow_id, $season_number);

echo $tvseason->getName();

The getter returns a TVSeason object.

Get a TV Episode

$item      = new Item($tmdb);
$tvepisode = $item->getTVEpisode($tvshow_id, $season_number, $episode_number);

echo $tvepisode->getName();

The getter returns a TVEpisode object.

Collection

Search a Collection

$search    = new Search($tmdb);
$responses = $search->collection('alien');

The search returns Generator object of Result\Collection object.

See demo

Get a Collection

$item       = new Item($tmdb);
$collection = $item->getCollection($collection_id);

echo $collection->getName();

The getter returns a Collection object.

See demo

People

Search a People

$search    = new Search($tmdb);
$responses = $search->people('alec baldwin');

The search returns Generator object of Result\People object.

See demo

Get a People

$item   = new Item($tmdb);
$people = $item->getPeople($people_id);

echo $people->getName();

The getter returns a People object.

See demo

Company

Search a company

$search    = new Search($tmdb);
$responses = $search->company('lucasfilms');

The search returns Generator object of Result\Company object.

See demo

Get a Company

$item   = new Item($tmdb);
$company = $item->getCompany($company_id);

echo $company->getName();

The getter returns a Company object.

See demo

Find by an external ID

$find = new Find($tmdb);
$responses = $find->imdb('tt0076759');

The find method makes it easy to search for objects in TMDb database by an external id.

Each sources has his proper methods: imdb, tvdb, tvrage, facebook, twitter, instagram.

The find returns a Result\Find object. Each types of objects can be getted by a specific method. The returns is a Generator object of Result\[expected type] object.

$movies = $responses->getMovies();
$title  = $movies->current()->getTitle();

Object types	Methods	Generator of
movies	getMovies()	Result\Movie
peoples	getPeoples()	Result\People
TV shows	getTVShows()	Result\TVShow
TV episodes	getTVEpisodes()	Result\TVEpisode
TV Seasons	getTVSeasons()	Result\TVSeason

The supported external sources for each object are as follows.

	Movies	TV Shows	TV Seasons	TV Episodes	People
IMDb ID	✓	✓	✕	✓	✓
TVDb ID		✓	✓	✓	✕
Freebase MID	not implemented
Freebase ID	not implemented
TVRage	✕	✓	✓	✓	✓
Facebook	✓	✓	✕	✕	✓
Twitter	✓	✓	✕	✕	✓
Instagram	✓	✓	✕	✕	✓

Authentication

The connection to your account is in 3 steps:

• Getting a request token
• Connection to TMDb website
• Create a session

Getting a request token

$tmdb = Factory::create()->getTmdb('your_api_key');

$Auth = new Auth($tmdb);
echo $Auth->getRequestToken();

Connect to TMDb website

$tmdb = Factory::create()->getTmdb('your_api_key');

$Auth = new Auth($tmdb);
$Auth->connect($_POST['request_token']);

This call redirect the page to TMDb website login page for identification and authorisations. By default, after the connection, the user stay on TMDb website. To redirect to your website after the connection, use the following code:

$tmdb = Factory::create()->getTmdb('your_api_key');

$Auth = new Auth($tmdb);
$Auth->connect($_POST['request_token'], 'http://your_url');

Create a session

To use all account methods, we must use a valid session.

$tmdb = Factory::create()->getTmdb('62dfe9839b8937e595e325a4144702ad');

$Auth = new Auth($tmdb);
echo $Auth->createSession($_POST['request_token']);

Media Helper

All media informations delivered by the library are relative pathfile.

To get a valid media URL, use the Media class to generate the URL and check the media size

$media = new Media($tmdb);
$url = $media->getPosterUrl('/AbJBXaVPrdXROwb8KmgWUPU2XJX.jpg');

The following type of media are supported :

• Backdrop
• Poster
• Logo
• Profile
• Still

Unit Testing

You can run the unit test suites using the following command in the library's source directory:

$ make test

About

Submitting bugs and feature requests

Bugs and feature request are tracked on GitHub

Author

Vincent Faliès - [e-mail]

License

VfacTmdb is licensed under the MIT License - see the LICENSE file for details