README

PHP wrapper package to interact with the The Movie Database (TMDB) API.

Important

You need to create an account on TMDB and get an API key to use this package. It's free and easy to do, you can read this guide to get started.

Warning

This package is under development.

Requirements

PHP 8.1 and later.

Note

Package guzzlehttp/guzzle will be installed automatically by composer.

About

This package uses repository pattern to interact with the TMDB API. Each repository represents an API category like Movies, Search, Trending, etc. And each endpoint of API is a method in repository, like details() for Movies, movie() for Search, all() for Trending, etc. If you know TMDB API, you will understand this package easily.

This is NOT official TMDB API PHP wrapper, you can check php-tmdb/api if you want official package.

Why this package?

All current PHP packages to interact with the TMDB API are not up-to-date and I need a modern and easy-to-use package to interact with the TMDB API. So I decided to create this package. You can check roadmap to see what I plan to do with this package.

Installation

You can install the package via composer:

composer require kiwilan/php-tmdb

Usage of API

Basic example

You have just to use client() static method to get new instance of Tmdb class with your API key. After that, you can use repositories with chained methods to interact with the TMDB API, first chained method is a repository, corresponding to a category of the API. And second chained method is an endpoint of the API.

use Kiwilan\Tmdb\Tmdb;

$results = Tmdb::client('API_KEY')
    ->search()
    ->movie(query: 'the lord of the rings'); // ?\Kiwilan\Tmdb\Results\MovieResults

Collection

Collection: Details

Get collection details by ID.

use Kiwilan\Tmdb\Tmdb;

$collection = Tmdb::client('API_KEY')
    ->collections()
    ->details(collection_id: 119); // ?\Kiwilan\Tmdb\Models\TmdbCollection

Collection: Images

Get the images that belong to a collection.

$images = Tmdb::client('API_KEY')
    ->collections()
    ->images(collection_id: 119); // ?\Kiwilan\Tmdb\Models\Images\TmdbImages

Collection: Translations

Get the translations that belong to a collection.

$translations = Tmdb::client('API_KEY')
    ->collections()
    ->translations(collection_id: 119); // ?\Kiwilan\Tmdb\Models\Translations\TmdbTranslations

Companies

Companies: Details

Get the company details by ID.

use Kiwilan\Tmdb\Tmdb;

$company = Tmdb::client('API_KEY')
    ->companies()
    ->details(company_id: 12); // ?\Kiwilan\Tmdb\Models\TmdbCompany

Credits

Credits: Details

Get a movie or TV credit details by ID.

use Kiwilan\Tmdb\Tmdb;

$credit = Tmdb::client('API_KEY')
    ->credits()
    ->details(credit_id: '5256c8b219c2956ff6047cd8'); // ?\Kiwilan\Tmdb\Models\TmdbCredit

Movie Lists

Movie Lists: Now Playing

Get a list of movies that are currently in theatres.

use Kiwilan\Tmdb\Tmdb;

$now_playing = Tmdb::client('API_KEY')
    ->movieLists()
    ->nowPlaying(); // ?\Kiwilan\Tmdb\Results\MovieResults

Movie Lists: Popular

Get a list of movies ordered by popularity.

$popular = Tmdb::client('API_KEY')
    ->movieLists()
    ->popular(); // ?\Kiwilan\Tmdb\Results\MovieResults

Movie Lists: Top Rated

Get a list of movies ordered by rating.

$top_rated = Tmdb::client('API_KEY')
    ->movieLists()
    ->topRated(); // ?\Kiwilan\Tmdb\Results\MovieResults

Movie Lists: Upcoming

Get a list of movies that are being released soon.

$upcoming = Tmdb::client('API_KEY')
    ->movieLists()
    ->upcoming(); // ?\Kiwilan\Tmdb\Results\MovieResults

Movies

Movies: Details

Get the top level details of a movie by ID (you can use append_to_response option to get more details).

use Kiwilan\Tmdb\Tmdb;

$movie = Tmdb::client('API_KEY')
    ->movies()
    ->details(movie_id: 120); // ?\Kiwilan\Tmdb\Models\TmdbMovie

Networks

Networks: Details

Get the details of a network by ID.

use Kiwilan\Tmdb\Tmdb;

$network = Tmdb::client('API_KEY')
    ->networks()
    ->details(network_id: 49); // ?\Kiwilan\Tmdb\Models\TvSeries\TmdbNetwork

Search

Search: Collection

Search for collections by their original, translated and alternative names.

use Kiwilan\Tmdb\Tmdb;

$results = Tmdb::client('API_KEY')
    ->search()
    ->movie(query: 'the lord of the rings');

$collections = $results->getResults(); // \Kiwilan\Tmdb\Models\TmdbCollection[]
$firstCollection = $results->getFirstResult(); // ?\Kiwilan\Tmdb\Models\TmdbCollection

You can use options into your search:

use Kiwilan\Tmdb\Tmdb;
use Kiwilan\Tmdb\Query\SearchCollectionQuery;

$results = Tmdb::client('API_KEY')
    ->search()
    ->collection(query: 'le seigneur des anneaux', params: new SearchCollectionQuery(
        include_adult: true,
        language: 'fr-FR',
        page: 1,
        year: 2001,
    ));

Search: Movie

Search for movies by their original, translated and alternative titles.

use Kiwilan\Tmdb\Tmdb;

$results = Tmdb::client('API_KEY')
    ->search()
    ->movie(query:'the fellowship of the ring');

$movies = $results->getResults(); // \Kiwilan\Tmdb\Models\TmdbMovie[]
$firstMovie = $results->getFirstResult(); // ?\Kiwilan\Tmdb\Models\TmdbMovie

You can use options into your search:

use Kiwilan\Tmdb\Tmdb;
use Kiwilan\Tmdb\Query\SearchMovieQuery;

$results = Tmdb::client('API_KEY')
    ->search()
    ->movie(query: 'le seigneur des anneaux', params: new SearchMovieQuery(
        include_adult: true,
        language: 'fr-FR',
        primary_release_year: 2001,
        page: 1,
        region: 'en-US',
        year: 2001,
    ));

Search: TV

Search for TV shows by their original, translated and also known as names.

use Kiwilan\Tmdb\Tmdb;

$results = Tmdb::client('API_KEY')
    ->search()
    ->tv(query: 'game of thrones');

$tvSeries = $results->getResults(); // \Kiwilan\Tmdb\Models\TmdbTvSeries[]
$firstTvSeries = $results->getFirstResult(); // ?\Kiwilan\Tmdb\Models\TmdbTvSeries

You can use options into your search:

use Kiwilan\Tmdb\Tmdb;
use Kiwilan\Tmdb\Query\SearchTvSeriesQuery;

$results = Tmdb::client('API_KEY')
    ->search()
    ->tv(query: 'game of thrones', params: new SearchTvSeriesQuery(
        first_air_date_year: 2011,
        include_adult: true,
        language: 'fr-FR',
        page: 1,
        year: 2011,
    ));

TV Series List

TV Series List: Airing Today

Get a list of TV shows airing today.

$airing_today = Tmdb::client('API_KEY')
    ->tvSeriesList()
    ->airingToday(); // ?\Kiwilan\Tmdb\Results\TvSerieResults

TV Series List: On The Air

Get a list of TV shows that air in the next 7 days.

$on_the_air = Tmdb::client('API_KEY')
    ->tvSeriesList()
    ->onTheAir(); // ?\Kiwilan\Tmdb\Results\TvSerieResults

TV Series List: Popular

Get a list of TV shows ordered by popularity.

$popular = Tmdb::client('API_KEY')
    ->tvSeriesList()
    ->popular(); // ?\Kiwilan\Tmdb\Results\TvSerieResults

TV Series List: Top Rated

Get a list of TV shows ordered by rating.

$top_rated = Tmdb::client('API_KEY')
    ->tvSeriesList()
    ->topRated(); // ?\Kiwilan\Tmdb\Results\TvSerieResults

TV Series

TV Series: Details

Get the details of a TV show (you can use append_to_response option to get more details).

use Kiwilan\Tmdb\Tmdb;

$tvSeries = Tmdb::client('API_KEY')
    ->tvSeries()
    ->details(series_id: 1399); // ?\Kiwilan\Tmdb\Models\TmdbTvSeries

TV Seasons

TV Seasons: Details

Query the details of a TV season (you can use append_to_response option to get more details).

use Kiwilan\Tmdb\Tmdb;

$season = Tmdb::client('API_KEY')
    ->tvSeasons()
    ->details(series_id: 1399, season_number: 1); // ?\Kiwilan\Tmdb\Models\TmdbSeason

TV Episodes

TV Episodes: Details

Query the details of a TV episode (you can use append_to_response option to get more details).

use Kiwilan\Tmdb\Tmdb;

$episode = Tmdb::client('API_KEY')
    ->tvEpisodes()
    ->details(series_id: 1399, season_number: 1, episode_number: 1); // ?\Kiwilan\Tmdb\Models\TmdbEpisode

Advanced

Results

For any method that returns a list of results, you can use multiple methods:

use Kiwilan\Tmdb\Tmdb;

$movies = Tmdb::client('API_KEY')
    ->movieLists()
    ->popular(); // ?\Kiwilan\Tmdb\Results\MovieResults

$results = $movies->getResults(); // \Kiwilan\Tmdb\Models\TmdbMovie[]
$firstResult = $movies->getFirstResult(); // ?\Kiwilan\Tmdb\Models\TmdbMovie
$lastResult = $movies->getLastResult(); // ?\Kiwilan\Tmdb\Models\TmdbMovie
$filterResults = $movies->filter(fn (\Kiwilan\Tmdb\Models\TmdbMovie $movie) => $movie->getVoteAverage() > 8); // \Kiwilan\Tmdb\Models\TmdbMovie[]
$findResult = $movies->find(fn (\Kiwilan\Tmdb\Models\TmdbMovie $movie) => $movie->getVoteAverage() > 8); // ?\Kiwilan\Tmdb\Models\TmdbMovie

Images

For any model with image (poster, backdrop, logo, profile, still), you can use multiple methods:

use Kiwilan\Tmdb\Tmdb;

$movie = Tmdb::client('API_KEY')
    ->movies()
    ->details(movie_id: 120); // ?\Kiwilan\Tmdb\Models\TmdbMovie

$poster_path = $movie->getPosterPath(); // string|null (path to poster)
$poster_url = $movie->getPosterUrl(); // string|null (URL to poster)
$poster_image = $movie->getPosterImage(); // string|null (binary image)
$success = $movie->savePosterImage('path/to/save/poster.jpg'); // bool (true if success)

You can change the size of the image with size option, available for get*Url, get*Image and save*Image methods:

use Kiwilan\Tmdb\Tmdb;
use Kiwilan\Tmdb\Enums\PosterSize;

$movie = Tmdb::client('API_KEY')
    ->movies()
    ->details(movie_id: 120); // ?\Kiwilan\Tmdb\Models\TmdbMovie

$poster_url = $movie->getPosterUrl(size: PosterSize::W500); // string|null (URL to poster)

These methods are available for Poster, Backdrop, Logo, Profile and Still.

Append to response

TMDB offers an easy way to get more details with append_to_response option. You can add more data in same request, it's really useful to get all data you need in one request.

append_to_response is an easy and efficient way to append extra requests to any top level namespace. The movie, TV show, TV season, TV episode and person detail methods all support a query parameter called append_to_response. This makes it possible to make sub requests within the same namespace in a single HTTP request. Each request will get appended to the response as a new JSON object. From https://developer.themoviedb.org/docs/append-to-response

To know which methods support append_to_response, check if method has append_to_response parameter (always optional and at the end of parameters). And to know what you can add, check the official documentation.

Example with append_to_response:

use Kiwilan\Tmdb\Tmdb;

$movie = Tmdb::client('API_KEY')
    ->movies()
    ->details(movie_id: 120, append_to_response: ['credits' ,'videos']); // ?\Kiwilan\Tmdb\Models\TmdbMovie

Get raw data

If you want to get raw data from TMDB API, you can use getRawData() method and getRawDataKey() method to get a specific key.

Note

If a key hasn't dedicated method, you can use getRawDataKey() method to get it but don't hesitate to open an issue to ask for a dedicated method.

use Kiwilan\Tmdb\Tmdb;

$movie = Tmdb::client('API_KEY')
    ->movies()
    ->details(movie_id: 120); // ?\Kiwilan\Tmdb\Models\TmdbMovie

$raw_data = $movie->getRawData(); // array
$raw_title_key = $movie->getRawDataKey('title'); // mixed

Send raw request

If you want to send a raw request to TMDB API, you can use raw() method, API key will be added automatically.

use Kiwilan\Tmdb\Tmdb;

$response = Tmdb::client(apiKey())
    ->raw()
    ->url('/movie/now_playing', ['language' => 'en-US', 'page' => 1]); // ?Kiwi\Tmdb\Repositories\RawRepository

$response->isSuccess(); // bool
$response->getStatusCode(); // int
$response->getBody(); // array
$response->getUrl(); // string

Testing

composer test

Contributing

A fix? A new feature? A typo? You're welcome to contribute to this project. Just open a pull request.

Roadmap

Account
Authentication
Certifications
- Movie Certifications
- TV Certifications
Changes
- Movie List
- People List
- TV List
~~Collections~~
- ~~Details~~
- ~~Images~~
- ~~Translations~~
Companies
- ~~Details~~
- Alternative Names
- Images
Configuration
~~Credits~~
- ~~Details~~
Discover
- Movie
- TV
Find
- By ID
Genres
- Movie List
- TV List
Guest Sessions
Keywords
- Details
- Movies (deprecated)
Lists
~~Movie Lists~~
- ~~Now playing~~
- ~~Popular~~
- ~~Top Rated~~
- ~~Upcoming~~
Movies
- ~~Details~~
- Account States
- Alternative Titles: for v1
- Changes
- Credits: for v1
- External IDs
- Images
- Keywords: for v1
- Latest
- Lists
- Recommendations: for v1
- Release Dates: for v1
- Reviews: for v1
- Similar: for v1
- Translations
- Videos: for v1
- Watch Providers
- Add Rating
- Delete Rating
Networks
- ~~Details~~
- Alternative Names
- Images
People Lists
- Popular
People
- Details: for v1
- Changes
- Combined Credits
- External IDs
- Images
- Latest
- Movie Credits
- TV Credits
- Translations
Reviews
- Details
Search
- ~~Collection~~
- Company: for v1
- Keyword: for v1
- ~~Movie~~
- Multi: for v1
- Person: for v1
- TV
~~Trending~~
- ~~All~~
- ~~Movie~~
- TV
- ~~People~~
~~TV Series List~~
- ~~Airing Today~~
- ~~On The Air~~
- ~~Popular~~
- ~~Top Rated~~
TV Series
- ~~Details~~
- Account States
- Aggregate Credits: for v1.5
- Alternative Titles: for v1
- Changes
- Content Ratings
- Credits: for v1
- Episode Groups
- External IDs
- Images
- Keywords: for v1
- Latest: for v1
- List
- Recommendations: for v1
- Reviews: for v1
- Screened Theatrically
- Similar: for v1
- Translations
- Videos: for v1
- Watch Providers
- Add Rating
- Delete Rating
TV Season
- ~~Details~~
- Account States
- Aggregate Credits: for v1.5
- Changes
- Credits: for v1
- External IDs
- Images
- Translations
- Videos: for v1
- Watch Providers
TV Episode
- ~~Details~~
- Account States
- Changes
- Credits: for v1
- External IDs
- Images
- Translations
- Videos: for v1
- Add Rating
- Delete Rating
TV Episode Group
- Details
Watch Providers
- Available Regions
- Movie Providers
- TV Providers

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

TMDB for their awesome API
spatie for spatie/package-skeleton-php
Ewilan Rivière author of this package
All Contributors

License

The MIT License (MIT). Please see License File for more information.

kiwilan / php-tmdb

Maintainers

Details

README

Requirements

About

Installation

Usage of API

Basic example

Collection

Companies

Credits

Movie Lists

Movies

Networks

Search

Trending

TV Series List

TV Series

TV Seasons

TV Episodes

Advanced

Results

Images

Append to response

Get raw data

Send raw request

Testing

Contributing

Roadmap

Changelog

Credits

License