PHPackages chiiya/tmdb-php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. chiiya/tmdb-php ActiveLibrary[API Development](/categories/api) chiiya/tmdb-php =============== PHP SDK for the TMDB API 1.1.0(1mo ago)73.6k↑63.1%1[3 PRs](https://github.com/chiiya/tmdb-php/pulls)1MITPHPPHP ^8.2CI passing Since Jun 14Pushed 1mo ago2 watchersCompare [ Source](https://github.com/chiiya/tmdb-php)[ Packagist](https://packagist.org/packages/chiiya/tmdb-php)[ Docs](https://github.com/chiiya/tmdb-php)[ GitHub Sponsors](https://github.com/chiiya)[ RSS](/packages/chiiya-tmdb-php/feed)WikiDiscussions master Synced 2d ago READMEChangelog (1)Dependencies (15)Versions (18)Used By (1) [![TMDB PHP](./.github/tmdb-php.png)](./.github/tmdb-php.png) [![](https://camo.githubusercontent.com/1d422ab240744ab33eee3c9b602107c168347c71b114c7d58b0786ac23c257dd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6368696979612f746d64622d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/chiiya/tmdb-php) [![](https://camo.githubusercontent.com/879446f12f96b5c53d897f5b4eec0ac99d7d625cbc44cd31392b738b096f561d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6368696979612f746d64622d7068702f7068702d63732d66697865722e796d6c3f6272616e63683d6d6173746572)](https://github.com/chiiya/tmdb-php/actions?query=workflow%3Alint+branch%3Amaster) [![](https://camo.githubusercontent.com/2d2273ce461fbdca6b208d7aee6b3827ab54a3893d25a534884466de01ea229e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6368696979612f746d64622d7068702e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/2d2273ce461fbdca6b208d7aee6b3827ab54a3893d25a534884466de01ea229e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6368696979612f746d64622d7068702e7376673f7374796c653d666c61742d737175617265) A strongly-typed PHP SDK for the TMDB (The Movie Database) API, providing complete coverage of all non-user related APIv3 endpoints with full type safety and IDE autocompletion support. *Looking for a Laravel package? Check out [`chiiya/laravel-tmdb`](https://github.com/chiiya/laravel-tmdb).* Index ----- [](#index) ``` > Installation > Quickstart > Core Concepts > Repositories > Query Parameters > FAQ > Changelog > Contributing > License ``` Installation ------------ [](#installation) Install the package via Composer: ``` composer require chiiya/tmdb-php ``` ### Requirements [](#requirements) - PHP 8.2 or higher - TMDB API v4 access token ### API Token Setup [](#api-token-setup) You need to create a v4 auth token for the TMDB API. You can find it under `API > API Read Access Token` in your TMDB account settings. Quick Start ----------- [](#quick-start) ``` use Chiiya\Tmdb\Http\Client; use Chiiya\Tmdb\Repositories\MovieRepository; // Create an authenticated client $client = Client::createAuthenticatedClient('your_v4_bearer_token'); // Create a repository $repository = new MovieRepository($client); // Get movie details $movie = $repository->getMovie(550); echo $movie->title; // "Fight Club" echo $movie->overview; // Movie description echo $movie->release_date->format('Y-m-d'); // "1999-10-15" ``` Core Concepts ------------- [](#core-concepts) ### Architecture [](#architecture) The library follows a repository pattern where each API domain has its own repository class: - **Repositories**: Handle API calls and return strongly-typed entities - **Entities**: Represent API response data with full type safety - **Query Parameters**: Provide type-safe parameter objects for API requests - **Responses**: Paginated response wrappers for list endpoints Repositories ------------ [](#repositories) The library provides repositories for all major TMDB API domains: ### MovieRepository [](#movierepository) Handles all movie-related API endpoints. ``` use Chiiya\Tmdb\Repositories\MovieRepository; $repository = new MovieRepository($client); $movie = $repository->getMovie(550); $credits = $repository->getCredits(550); $images = $repository->getImages(550); $videos = $repository->getVideos(550); $reviews = $repository->getReviews(550); $similar = $repository->getSimilarMovies(550); $recommendations = $repository->getRecommendations(550); $externalIds = $repository->getExternalIds(550); $titles = $repository->getAlternativeTitles(550); $keywords = $repository->getKeywords(550); $releaseDates = $repository->getReleaseDates(550); $translations = $repository->getTranslations(550); $watchProviders = $repository->getWatchProviders(550); $changes = $repository->getChanges(550); $popular = $repository->getPopular(); $nowPlaying = $repository->getNowPlaying(); $topRated = $repository->getTopRated(); $upcoming = $repository->getUpcoming(); $latest = $repository->getLatest(); ``` ### TvShowRepository [](#tvshowrepository) Handles all TV show-related API endpoints. ``` use Chiiya\Tmdb\Repositories\TvShowRepository; $repository = new TvShowRepository($client); $show = $repository->getTvShow(1399); // Game of Thrones $credits = $repository->getCredits(1399); $aggregateCredits = $repository->getAggregateCredits(1399); $images = $repository->getImages(1399); $videos = $repository->getVideos(1399); $reviews = $repository->getReviews(1399); $similar = $repository->getSimilar(1399); $recommendations = $repository->getRecommendations(1399); $externalIds = $repository->getExternalIds(1399); $titles = $repository->getAlternativeTitles(1399); $keywords = $repository->getKeywords(1399); $translations = $repository->getTranslations(1399); $watchProviders = $repository->getWatchProviders(1399); $changes = $repository->getChanges(1399); $contentRatings = $repository->getContentRatings(1399); $episodeGroups = $repository->getEpisodeGroups(1399); $screenedTheatrically = $repository->getScreenedTheatrically(1399); $popular = $repository->getPopular(); $airingToday = $repository->getAiringToday(); $onTheAir = $repository->getOnTheAir(); $topRated = $repository->getTopRated(); $latest = $repository->getLatest(); ``` ### Other Repositories [](#other-repositories) The library also includes repositories for: - **SearchRepository**: Search endpoints - **PersonRepository**: People/actors information - **TvSeasonRepository**: TV season details - **TvEpisodeRepository**: TV episode details - **CompanyRepository**: Production companies - **CollectionRepository**: Movie collections - **GenreRepository**: Movie and TV genres - **KeywordRepository**: Keywords - **ReviewRepository**: Reviews - **CreditRepository**: Credits - **ConfigurationRepository**: API configuration - **CertificationRepository**: Content ratings - **ChangeRepository**: Recent changes - **BrowseRepository**: Browse endpoints - **WatchProviderRepository**: Streaming providers - **NetworkRepository**: TV networks Query Parameters ---------------- [](#query-parameters) The library provides type-safe query parameter objects for API requests. All parameters implement the `QueryParameterInterface`. ### Common Parameters [](#common-parameters) ``` use Chiiya\Tmdb\Query\Language; use Chiiya\Tmdb\Query\Page; use Chiiya\Tmdb\Query\IncludeAdult; use Chiiya\Tmdb\Query\Region; use Chiiya\Tmdb\Query\Year; use Chiiya\Tmdb\Query\PrimaryReleaseYear; use Chiiya\Tmdb\Query\FirstAirDateYear; use Chiiya\Tmdb\Query\StartDate; use Chiiya\Tmdb\Query\EndDate; use Chiiya\Tmdb\Query\ExternalSource; use Chiiya\Tmdb\Query\AppendToResponse; // Language parameter $language = new Language('en-US'); // Pagination $page = new Page(1); // Include adult content $includeAdult = new IncludeAdult(true); // Region for watch providers $region = new Region('US'); // Year filters $year = new Year(2023); $primaryReleaseYear = new PrimaryReleaseYear(2023); $firstAirDateYear = new FirstAirDateYear(2023); // Date ranges $startDate = new StartDate('2023-01-01'); $endDate = new EndDate('2023-12-31'); // External source $externalSource = new ExternalSource('imdb_id'); // Append additional data to response $appendToResponse = new AppendToResponse([ AppendToResponse::IMAGES, AppendToResponse::CREDITS, AppendToResponse::WATCH_PROVIDERS, ]); ``` ### Using Parameters [](#using-parameters) ``` // Get movie with additional data $movie = $repository->getMovie(550, [ new Language('en-US'), new AppendToResponse([ AppendToResponse::IMAGES, AppendToResponse::CREDITS, AppendToResponse::WATCH_PROVIDERS, ]), ]); // Search with parameters $movies = $repository->searchMovies('action', [ new Language('en-US'), new Page(1), new IncludeAdult(false), new Year(2023), ]); ``` FAQ --- [](#faq) ### How do I handle API rate limits? [](#how-do-i-handle-api-rate-limits) The library handles rate limiting by sleeping for the necessary time (indicated by the `retry-after`header) when a rate limit error occurs. However, you should ensure your application stays within TMDB's rate limits to avoid hitting them frequently. ### Can I use this with Laravel? [](#can-i-use-this-with-laravel) Yes, but this is a standalone library. For Laravel integration, check out `chiiya/laravel-tmdb`. ### How do I get streaming provider information? [](#how-do-i-get-streaming-provider-information) Use the `AppendToResponse::WATCH_PROVIDERS` parameter when getting movie or TV show details: ``` $movie = $repository->getMovie(550, [ new AppendToResponse([AppendToResponse::WATCH_PROVIDERS]), ]); // Access by country code if (isset($movie->watch_providers['US'])) { $providers = $movie->watch_providers['US']; } ``` ### How do I get images with different sizes? [](#how-do-i-get-images-with-different-sizes) Images are returned with file paths. You need to construct the full URL using TMDB's image base URL: ``` $imageBaseUrl = 'https://image.tmdb.org/t/p/'; $size = 'w500'; // or 'original', 'w780', etc. $fullUrl = $imageBaseUrl . $size . $movie->poster_path; ``` ### How do I handle pagination? [](#how-do-i-handle-pagination) List responses include pagination information: ``` $movies = $repository->getPopular([new Page(1)]); echo $movies->page; // Current page echo $movies->total_pages; // Total pages echo $movies->total_results; // Total results // Access results foreach ($movies->results as $movie) { echo $movie->title; } // Does the response have more pages? $movies->hasMorePages(); // Returns true if there are more pages // Get next page $movies->getNextPageNumber(); ``` ### What API endpoints are not covered? [](#what-api-endpoints-are-not-covered) This library covers all non-account-related API endpoints. Specifically excluded are: - Account-related endpoints - Authentication endpoints - Guest Sessions - Lists - Account States - Rating endpoints - v4 API endpoints Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details. License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 55 — FairBetter than 97% of packages Maintenance93 Actively maintained with recent releases Popularity28 Limited adoption so far Community16 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor1 Top contributor holds 65.2% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~111 days Recently: every ~312 days Total 14 Last Release 36d ago Major Versions 0.2.9 → 1.0.02025-08-02 PHP version history (2 changes)0.1.0PHP ^8.1 1.0.0PHP ^8.2 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/15029301?v=4)[Elisha](/maintainers/chiiya)[@chiiya](https://github.com/chiiya) --- Top Contributors [![chiiya](https://avatars.githubusercontent.com/u/15029301?v=4)](https://github.com/chiiya "chiiya (45 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (16 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (8 commits)") --- Tags chiiyatmdb-php ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/chiiya-tmdb-php/health.svg) ``` [![Health](https://phpackages.com/badges/chiiya-tmdb-php/health.svg)](https://phpackages.com/packages/chiiya-tmdb-php) ``` ### Alternatives [statamic/cms The Statamic CMS Core Package 4.8k3.6M987](/packages/statamic-cms)[tencentcloud/tencentcloud-sdk-php TencentCloudApi php sdk 3741.3M46](/packages/tencentcloud-tencentcloud-sdk-php)[neuron-core/neuron-ai The PHP Agentic Framework. 2.0k656.1k38](/packages/neuron-core-neuron-ai)[eslazarev/wildberries-sdk Wildberries OpenAPI clients (generated). 273.0k](/packages/eslazarev-wildberries-sdk)[avalara/avataxclient Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API. 528.5M7](/packages/avalara-avataxclient)[files.com/files-php-sdk Files.com PHP SDK 2481.1k](/packages/filescom-files-php-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)