包简介

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

README 文档

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

Configuration

Configuration: Countries

Get the list of countries (ISO 3166-1 tags) used throughout TMDB.

use Kiwilan\Tmdb\Tmdb;

$company = Tmdb::client('API_KEY')
    ->configuration()
    ->countries(); // ?\Kiwilan\Tmdb\Models\Common\TmdbCountry[]

Configuration: Languages

Get the list of languages (ISO 639-1 tags) used throughout TMDB.

use Kiwilan\Tmdb\Tmdb;

$company = Tmdb::client('API_KEY')
    ->configuration()
    ->languages(); // ?\Kiwilan\Tmdb\Models\Common\TmdbLanguage[]

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
- Details
- ~~Countries~~
- Jobs
- ~~Languages~~
- Primary Translations
- Timezones
~~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 适用场景与选型建议

kiwilan/php-tmdb 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 405 次下载、GitHub Stars 达 3，最近一次更新时间为 2024 年 09 月 11 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「php」「api」「tv」「tmdb」「movie」「series」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 kiwilan/php-tmdb 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 kiwilan/php-tmdb 我们能提供哪些服务？

定制开发 / 二次开发

基于 kiwilan/php-tmdb 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 kiwilan/php-tmdb 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

theodorejb/phaster 6

A PSR-7 compatible library for making CRUD API endpoints

mrcnpdlk/xmdb-api 0

xMDB parser

evinkuraga/tmdb-api 0

PHP wrapper for TMDB (TheMovieDatabase) API v3. Supports two types of approaches, one modelled with repositories, models and factories. And the other by simple array access to RAW data from The Movie Database.

evinkuraga/tmdb-laravel 2

This is a fork of the package php-tmdb/laravel. Instead of waiting for the maintainer to update the php-tmdb/api package to reflect the latest changes from the API, I've decided to fix these. These packages are actively used for http://flixi.com, which means these we will be most likely maintaining

foxtes/alfabank-rest 1

Alfabank REST API integration

bjthecod3r/laravel-tmdb 0

A fluent, fully-typed Laravel wrapper for The Movie Database (TMDB) API.

kiwilan/php-tmdb

包简介

关键字：

README 文档

README

Requirements

About

Installation

Usage of API

Basic example

Collection

Companies

Configuration

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

kiwilan/php-tmdb 适用场景与选型建议

与 kiwilan/php-tmdb 相关的其它包

统计信息

GitHub 信息

其他信息