letsplaybar / tvdb
A TVDB API wrapper for Laravel.
Requires
- php: ^7.2
- ext-curl: *
- ext-json: *
This package is auto-updated.
Last update: 2024-10-08 10:35:41 UTC
README
The letsplaybar/tvdb
package provides easy to use functions that help you interact with the TVDB API.
Installation
You can install the package via composer:
composer require letsplaybar/tvdb
Publish the config file with the following artisan command:
php artisan vendor:publish --provider="Letsplaybar\TVDB\TVDBServiceProvider"
Configuration
The publish command above will publish a tvdb.php
config file to your Laravel config folder. Be sure to tweak the values with your personal API details.
I recommend not touching the config file, but rather defining your API details in your project's .env
file, like so:
TVDB_API_KEY=
TVDB_USER_KEY=
TVDB_USERNAME=
TVDB_LANGUAGE=
you can get these data on thetvdb.com
Value for LANGUAGE can found here: https://api.thetvdb.com/languages in abbreviation Attribute
Don't forget to clear recache your config. (php artisan config:cache
)
Usage
Finding series by ID
The getSeries
function returns a Series
object.
// Find a series by its TVDB ID
// ID: 73739 (Lost)
$result = TVDB::getSeries(73739);
echo $result->title; // "Lost"
Searching for series
The search
function returns an array of Series
objects, or an empty array if no results are found.
// Search by title
$results = TVDB::search('Planet Earth');
// Search by IMDB ID
$results = TVDB::search(['imdbId' => 'tt5491994']);
// Search by zap2it ID
$results = TVDB::search(['zap2itId' => 'SH303483']);
Getting series images
In order get an array of a series' images, you need to specify the type of image you'd like to retrieve. Available types are listed below.
/*
* Get the images of the series by TVDB ID
* ID: 73739 (Lost)
*
* Available image types:
* - TVDB::IMAGE_TYPE_FANART
* - TVDB::IMAGE_TYPE_POSTER
* - TVDB::IMAGE_TYPE_SEASON
* - TVDB::IMAGE_TYPE_SERIES
*/
$images = TVDB::getSeriesImages(73739, TVDB::IMAGE_TYPE_POSTER);
// Or get the images directly from a "Series" object
$series = TVDB::getSeries(73739);
$images = $series->getImages(TVDB::IMAGE_TYPE_FANART);
Getting series actors
The following options are available for retrieving an array of actors.
/*
* Get the actors of the series by TVDB ID
* ID: 73739 (Lost)
*/
$actors = TVDB::getSeriesActors(73739);
// Or get the actors directly from a "Series" object
$series = TVDB::getSeries(73739);
$actors = $series->getActors();
Getting series episodes
The TVDB API endpoint for retrieving episodes is paginated. This means that you will need to specify a page number when retrieving episodes.
/*
* Get the episodes of the series by TVDB ID
* ID: 73739 (Lost)
*
* The second parameter specifies the page (page 1 by default)
*/
$episodes = TVDB::getSeriesEpisodes(73739, 2);
// Or get the episodes directly from a "Series" object
$series = TVDB::getSeries(73739);
$episodes = $series->getEpisodes(2);
Example 1 - iterating over all episodes:
$page = 1;
do {
$episodes = TVDB::getSeriesEpisodes(73739, $page);
echo "Page $page has " . count($episodes) . " episodes. <br />";
$page++;
} while($episodes->hasNextPage());
/*
* Output:
* Page 1 has 100 episodes.
* Page 2 has 49 episodes.
*/
Example 2:
$episodes = TVDB::getSeriesEpisodes(73739);
foreach($episodes as $episode) {
echo $episode->name . '<br />';
}
Getting individual episodes
/*
* Retrieve the episode with ID 127131
* .. returns an "Episode" object
*/
$episode = TVDB::getEpisode(127131);
echo $episode->name; // "Pilot (1)"
Getting Movies
/*
* Retrieve the movie with ID 1
* .. returns an "Movies" object
*/
$movie = TVDB::getMovies(1);
echo $movie->translations[14]->name; // "Alita: Battle Angel"
Getting your TVDB JWT token
Sometimes it can be useful to retrieve your TVDB JWT token (for testing the API, for example).
echo TVDB::getToken();
Credits
License
The GPLv3 License (GPLv3). Please see License File for more information.