{"id":18578297,"url":"https://github.com/astrotomic/laravel-tmdb","last_synced_at":"2025-04-13T08:16:12.168Z","repository":{"id":41998210,"uuid":"409146013","full_name":"Astrotomic/laravel-tmdb","owner":"Astrotomic","description":"Interact with TMDB data in your Laravel application.","archived":false,"fork":false,"pushed_at":"2024-10-07T22:01:30.000Z","size":1823,"stargazers_count":36,"open_issues_count":5,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-22T16:04:53.489Z","etag":null,"topics":["api-client","database","eloquent","laravel","movie-database","movies-api","php","themoviedatabase","themoviedb","themoviedb-api","tmdb","tmdb-api","tmdb-movie","tmdb-rest-api","treeware"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Astrotomic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["Gummibeer","SarahSibert"],"issuehunt":"astrotomic","custom":["https://forest.astrotomic.info"]}},"created_at":"2021-09-22T09:43:36.000Z","updated_at":"2025-03-04T11:13:07.000Z","dependencies_parsed_at":"2022-09-07T11:42:04.730Z","dependency_job_id":"83d90c9a-19bc-48ea-8e58-a34ec4786e18","html_url":"https://github.com/Astrotomic/laravel-tmdb","commit_stats":{"total_commits":92,"total_committers":4,"mean_commits":23.0,"dds":"0.19565217391304346","last_synced_commit":"ee99a5d53f353c09a60c824ff9c88a116678c78b"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Astrotomic%2Flaravel-tmdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Astrotomic%2Flaravel-tmdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Astrotomic%2Flaravel-tmdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Astrotomic%2Flaravel-tmdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Astrotomic","download_url":"https://codeload.github.com/Astrotomic/laravel-tmdb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245755666,"owners_count":20667027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","database","eloquent","laravel","movie-database","movies-api","php","themoviedatabase","themoviedb","themoviedb-api","tmdb","tmdb-api","tmdb-movie","tmdb-rest-api","treeware"],"created_at":"2024-11-06T23:34:32.041Z","updated_at":"2025-03-27T00:07:44.427Z","avatar_url":"https://github.com/Astrotomic.png","language":"PHP","funding_links":["https://github.com/sponsors/Gummibeer","https://github.com/sponsors/SarahSibert","https://issuehunt.io/r/astrotomic","https://forest.astrotomic.info"],"categories":[],"sub_categories":[],"readme":"![](.github/banner.png)\n\n# Laravel TMDB\n\n[![Latest Version](http://img.shields.io/packagist/v/astrotomic/laravel-tmdb.svg?label=Release\u0026style=for-the-badge)](https://packagist.org/packages/astrotomic/laravel-tmdb)\n[![MIT License](https://img.shields.io/github/license/Astrotomic/laravel-tmdb.svg?label=License\u0026color=blue\u0026style=for-the-badge)](https://github.com/Astrotomic/laravel-tmdb/blob/master/LICENSE)\n[![Offset Earth](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-green?style=for-the-badge)](https://forest.astrotomic.info)\n[![Larabelles](https://img.shields.io/badge/Larabelles-%F0%9F%A6%84-lightpink?style=for-the-badge)](https://larabelles.com)\n\n[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/Astrotomic/laravel-tmdb/pest?style=flat-square\u0026logoColor=white\u0026logo=github\u0026label=Tests)](https://github.com/Astrotomic/laravel-tmdb/actions?query=workflow%3Apest)\n[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/Astrotomic/laravel-tmdb/phpcs?style=flat-square\u0026logoColor=white\u0026logo=github\u0026label=PHP+CS)](https://github.com/Astrotomic/laravel-tmdb/actions?query=workflow%3Aphpcs)\n\n[![Total Downloads](https://img.shields.io/packagist/dt/astrotomic/laravel-tmdb.svg?label=Downloads\u0026style=flat-square)](https://packagist.org/packages/astrotomic/laravel-tmdb)\n[![Trees](https://img.shields.io/ecologi/trees/astrotomic?style=flat-square)](https://forest.astrotomic.info)\n[![Carbon](https://img.shields.io/ecologi/carbon/astrotomic?style=flat-square)](https://forest.astrotomic.info)\n\n## Installation\n\n```bash\ncomposer require astrotomic/laravel-tmdb\nphp artisan vendor:publish --tag=tmdb-migrations\n```\n\n## Configuration\n\nAdd your [TMDB API v4 Token](https://www.themoviedb.org/settings/api) to the `config/services.php` file.\n\n**config/services.php**\n```php\nreturn [\n    // ...\n    \n    'tmdb' =\u003e [\n        'token' =\u003e env('TMDB_TOKEN'),\n    ],\n\n    // ...\n];\n```\n\nAfter that you can configure your language and region to be used by the package for some of the API requests.\nBy default we use `app()-\u003egetLocale()` for the language and a hardcoded `US` region.\nIt's recommended to call this in your `AppServiceProvider` but you can call the methods from everywhere in your codecase.\nIn case you want to run a specific callback with a region or language without changing the globally used ones you can use the `with` methods.\nThese will set the region or language to teh given one for the callback and automatically restore the old one after running the callback.\n\n```php\nuse Astrotomic\\Tmdb\\Facades\\Tmdb;\n\nTmdb::useLanguage('de');\nTmdb::useRegion('DE');\n\nTmdb::withLanguage('de', fn() =\u003e \\Astrotomic\\Tmdb\\Models\\Movie::find(335983));\nTmdb::withRegion('DE', fn() =\u003e \\Astrotomic\\Tmdb\\Models\\Movie::upcoming(20));\n```\n\n## Usage\n\n### Models\n\nThe easiest and most feature complete way to use the package are the provided models.\nThey come with custom query builders which do API calls if the requested model isn't found in your local database.\nThis only applies to the `find()` and sometimes the `all()` methods.\nSo if you only want to query your database, you can do so by using `whereKey()-\u003efirst()` for example.\n\n```php\nuse Astrotomic\\Tmdb\\Models\\Movie;\n\nMovie::find(335983);\nMovie::findMany([335983, 575788]);\nMovie::findOrFail(335983);\n```\n\nIt's recommended to prepare two \"static\" models to save future calls by calling their `all()` method once.\nThis will do one HTTP call per model and save multiple HTTP calls in the future.\n\n```php\nuse Astrotomic\\Tmdb\\Models\\MovieGenre;\nuse Astrotomic\\Tmdb\\Models\\TvGenre;\nuse Astrotomic\\Tmdb\\Models\\WatchProvider;\n\nMovieGenre::all();\nTvGenre::all();\nWatchProvider::all();\n```\n\nMost models use [spatie/laravel-translatable](https://github.com/spatie/laravel-translatable) with a slightly customized `translate()` method.\nThis will automatically load a missing translation if you request it.\n\n```php\nuse Astrotomic\\Tmdb\\Models\\Movie;\n\napp()-\u003esetLocale('en');\n$movie = Movie::find(335983);\n$movie-\u003etranslate('title', 'en'); // get title from DB\n$movie-\u003etranslate('title', 'de'); // get and persist title from API\n```\n\nIf you want to update the data in your database you can call the `updateFromTmdb()` method on any of the models.\nThis should be done a console command or queue job as it will do a lot of HTTP requests and can take few minutes per movie.\n\n```php\nuse Astrotomic\\Tmdb\\Models\\Movie;\n\nMovie::eachById(static function(Movie $movie): void {\n    $movie-\u003eupdateFromTmdb('de', ['credits']);\n});\n```\n\n#### Movie\n\nFirst of all you can also `find()` a movie with additional relations and they will also be queried from the API.\nTo do so you only have to call the `with()` method on the query before you call any of the `find()` methods.\n\n```php\nuse Astrotomic\\Tmdb\\Models\\Movie;\n\nMovie::with('genres')-\u003efind(335983);\nMovie::with('credits')-\u003efind(335983);\nMovie::with('cast')-\u003efind(335983);\nMovie::with('crew')-\u003efind(335983);\n```\n\nThere are some methods that do a HTTP call every single time.\nAnd if they accept a `$limit` argument they automically call each page till the amount of IDs is found.\nYou have to provide an explicit argument, in case you use `null` it will call **every** page.\nThis can result in several thousands of requests - so it's more recommended to provide a serious number.\n\n```php\nuse Astrotomic\\Tmdb\\Models\\Movie;\n\nMovie::popular(20);\nMovie::upcoming(20);\nMovie::toprated(20);\nMovie::trending(20);\nMovie::nowPlaying(20);\n\nMovie::findOrFail(335983)-\u003erecommendations(20);\nMovie::findOrFail(335983)-\u003esimilars(20);\n```\n\nYou can also get all watch providers (powered by [JustWatch](https://justwatch.com)) for a given movie.\nThese can be filtered/limited to a given region and/or type.\n\n```php\nuse Astrotomic\\Tmdb\\Models\\Movie;\nuse Astrotomic\\Tmdb\\Enums\\WatchProviderType;\n\nMovie::findOrFail(335983)-\u003ewatchProviders();\nMovie::findOrFail(335983)-\u003ewatchProviders('DE');\nMovie::findOrFail(335983)-\u003ewatchProviders(null, WatchProviderType::FLATRATE);\nMovie::findOrFail(335983)-\u003ewatchProviders('DE', WatchProviderType::FLATRATE);\n```\n\nAnd there are some helper methods on the movie model to easier work with some attributes.\n\n```php\nuse Astrotomic\\Tmdb\\Models\\Movie;\n\nMovie::findOrFail(335983)-\u003eruntime();\nMovie::findOrFail(335983)-\u003eposter();\nMovie::findOrFail(335983)-\u003ebackdrop();\n```\n\n#### Person\n\nThe person model has the same base model as the movie and general method API.\n\n```php\nuse Astrotomic\\Tmdb\\Models\\Person;\n\nPerson::with('movie_credits')-\u003efind(6384);\nPerson::trending(20);\nPerson::findOrFail(6384)-\u003eprofile();\n```\n\n### Images\n\nThere are some helper classes to generate image URLs for you with correct aspect-ratio.\nModels with image path attributes have a shortcut method which returns an instance of that image class.\n\n```php\nuse Astrotomic\\Tmdb\\Models\\Movie;\n\nMovie::find(335983)-\u003eposter();\nMovie::find(335983)-\u003ebackdrop();\n```\n\nThese image helpers will render a `\u003cimg/\u003e` tag if you echo them in your Blade templates.\nIn case they are casted to string they will return the image URL or a fallback one.\nYou can also call `url()` or `fallback()` to get one or the other URL and use them however you want.\n\n### Requests\n\nThe models use OOP request classes which you can also use your own.\nThese aren't the primary usage API but in case you need them, feel free to use.\n\n```php\nuse Astrotomic\\Tmdb\\Requests\\Movie\\Details;\n\nDetails::request(335983)-\u003esend()-\u003ejson();\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](https://github.com/Astrotomic/.github/blob/master/CONTRIBUTING.md) for details. You could also be interested in [CODE OF CONDUCT](https://github.com/Astrotomic/.github/blob/master/CODE_OF_CONDUCT.md).\n\n### Security\n\nIf you discover any security related issues, please check [SECURITY](https://github.com/Astrotomic/.github/blob/master/SECURITY.md) for steps to report it.\n\n## Credits\n\n- [Tom Witkowski](https://github.com/Gummibeer)\n- [Stefano Novelli](https://github.com/murdercode)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n\n## Treeware\n\nYou're free to use this package, but if it makes it to your production environment I would highly appreciate you buying the world a tree.\n\nIt’s now common knowledge that one of the best tools to tackle the climate crisis and keep our temperatures from rising above 1.5C is to [plant trees](https://www.bbc.co.uk/news/science-environment-48870920). If you contribute to my forest you’ll be creating employment for local families and restoring wildlife habitats.\n\nYou can buy trees at [ecologi.com/astrotomic](https://forest.astrotomic.info)\n\nRead more about Treeware at [treeware.earth](https://treeware.earth)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrotomic%2Flaravel-tmdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastrotomic%2Flaravel-tmdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrotomic%2Flaravel-tmdb/lists"}