A PHP Wrapper for use with the TMDB API.

Tests run with minimal, normal and development dependencies.

Buy me a coffee, or a beer :-)

My stomach will appreciate your donation!

Main features

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 <img> elements.

Attention newcomers to php

If you are new to php and starting a project to learn, I'd recommend you skip down to the installation, and then follow the quickstart that's just for you!

I do advise you to take a broader look later on what all these PSR standards mean and do for the php community :-).

PSR Compliance

We try to leave as many options open to the end users of this library, as such with 4.0 changes have been made to introduce PSR compliance where we can. You bring the dependencies you prefer that are compliant with PSR standards, register the listeners, and we handle the rest.

PSR-3: Logger Interface, jump to section.
- Logs TMDB API exceptions, jump to section.
- Logs PSR-18 client exceptions, jump to section.
- Logs requests and responses, jump to section.
- Logs response hydration, jump to section.
- Logs caching behavior , jump to section.
PSR-6: Caching Interface, jump to section.
PSR-7: HTTP Message Interface
- Requests and responses will be modified via relevant event listeners.
PSR-12: Extended Coding Style.
- Work in progress, I'll do my best to finish before 4.1 but there is a lot to review and refactor. It would be nice to get contributions going our way helping out with this massive task. I can imagine it may take several months of doing small bits here and there to achieve this.
PSR-14: Event Dispatcher, jump to section.
- Register our listeners and events, we handle the rest.
PSR-16: Simple Cache, by adapting to PSR-6
- Although we do not implement this at the current stage, there are plenty of adapters converting PSR-16 implementations to PSR-6.
- We might rework this at a later stage to prevent the extra dependencies that the php-http/cache-plugin brings along.
PSR-17: HTTP Factories
- Bring along the http factories of your choice.
PSR-18: HTTP Client
- Bring along the PSR-18 http client of your choice.

Framework implementations

Symfony (maintained by php-tmdb developers)
- php-tmdb/symfony
Laravel (community maintained)
- php-tmdb/laravel

Installation

Install composer.

Before we can install the api library, you need to install a set of dependencies that provide the following implementations.

Dependencies you have to fulfill yourself

For PSR-7: HTTP Message Interface, for example nyholm/psr7.
For PSR-14: Event Dispatcher, for example symfony/event-dispatcher.
For PSR-17: HTTP Factories, for example nyholm/psr7.
For PSR-18: HTTP Client, for example guzzlehttp/guzzle.

I urge you to implement the optional caching implementation

When making use of caching, make sure to also include php-http/cache-plugin in composer, this plugin handles the logic for us, so we don't have to re-invent the wheel. You are however also free to choose to implement your own cache listener, or add the caching logic inside the http client of your choice.

composer require php-http/cache-plugin:^1.7

Even though themoviedb.org disabled rate limiting since the end of 2019, I'd still recommend enabling the cache to make your application run a bit smoother. As such the 427 retry subscriber in previous versions is not present anymore.

For PSR-6: Caching Interface, for example symfony/cache.
For PSR-16: Simple Cache, with an PSR-6 adapter for example symfony/cache, then use the PSR-16 to PSR-6 adapter.

Not only will this make your application more responsive, by loading from cache when we can, it also decreases the amount of requests we need to send.

Optional dependencies

For PSR-3: Logger Interface, for example monolog/monolog.

Install php-tmdb/api

If the required dependencies above are met, you are ready to install the library.

composer require php-tmdb/api:^4

Include Composer's autoloader:

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

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

New to PSR standards or composer?

If you came here looking to start a fun project to start learning, the above might seem a little daunting.

Don't worry! The documentation here was setup with beginners in mind as well.

We also provide a bunch of examples in the examples/ folder.

To get started;

composer require php-tmdb/api:^4 symfony/event-dispatcher guzzlehttp/guzzle symfony/cache monolog/monolog nyholm/psr7

Now that we have everything we need installed, let's get started setting up to be able to use the library.

Quick setup

Review the setup files below and go over the examples folder, for example examples/movies/api/get.php or examples/movies/api/get.php files.

Constructing the Client

If you have chosen different implementations than the examples suggested beforehand, obviously all the upcoming documentation won't match. Adjust accordingly to your dependencies, we will go along with the examples given earlier.

Minimal setup
Minimal setup with psr-6 caching
Full setup
- Includes logging
- Includes caching
- Includes filtering by region
- Includes filtering by language
- Includes filtering by adult content

General API Usage

If you're looking for a simple array entry point the API namespace is the place to be, however we recommend you use the repositories and model's functionality up ahead.

use Tmdb\Client;

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

If you want to provide any other query arguments.

use Tmdb\Client;

$client = new Client();
$movie = $client->getMoviesApi()->getMovie(550, ['language' => 'en']);

For all further calls just review the unit tests or examples provided, or the API classes themselves.

Model Usage

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.

use Tmdb\Repository\MovieRepository;
use Tmdb\Client;

$client = new Client();
$repository = new MovieRepository($client);
$movie = $repository->load(87421);

echo $movie->getTitle();

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

use Tmdb\Repository\MovieRepository;
use Tmdb\Client;

$client = new Client();
$repository = new MovieRepository($client);
$topRated = $repository->getTopRated(['page' => 3]);
// or
$popular = $repository->getPopular();

For all further calls just review the unit tests or examples provided, or the model's themselves.

Event Dispatching

We (can) dispatch the following events inside the library, which by using event listeners you could modify some behavior.

HTTP Client exceptions

Tmdb\Event\HttpClientExceptionEvent
- Allows to still set a successful response if the error can be corrected, by calling $event->isPropagated() in your listener, this does require you to provide a PSR-7 response object and set it with $event->setResponse($response).

Api

Install / Use

README