PHPackages                             adrenth/thetvdb - 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. adrenth/thetvdb

Abandoned → [adrenth/thetvdb2](/?search=adrenth%2Fthetvdb2)ArchivedLibrary[API Development](/categories/api)

adrenth/thetvdb
===============

API Client for thetvdb.com

0.1.8(10y ago)4701MITPHPPHP >=5.5

Since Sep 24Pushed 10y ago1 watchersCompare

[ Source](https://github.com/adrenth/thetvdb)[ Packagist](https://packagist.org/packages/adrenth/thetvdb)[ Docs](http://github.com/adrenth/thetvdb)[ RSS](/packages/adrenth-thetvdb/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependencies (5)Versions (11)Used By (0)

adrenth/thetvdb
===============

[](#adrenththetvdb)

[![Build Status](https://camo.githubusercontent.com/9e634448d90dae4564f5c58903a5b3bfa29048ddcfc14274f70bb2f9bf8855c0/68747470733a2f2f7472617669732d63692e6f72672f616472656e74682f746865747664622e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/adrenth/thetvdb)[![Latest Stable Version](https://camo.githubusercontent.com/77d951f956f769e10633d49da02f72426a165637894b0ca33953ae377f774ec4/68747470733a2f2f706f7365722e707567782e6f72672f616472656e74682f746865747664622f762f737461626c65)](https://packagist.org/packages/adrenth/thetvdb) [![Total Downloads](https://camo.githubusercontent.com/ef672d23012c038b612635e1629b7d2f63f4e2435a9223e970a8a223d69ef9dd/68747470733a2f2f706f7365722e707567782e6f72672f616472656e74682f746865747664622f646f776e6c6f616473)](https://packagist.org/packages/adrenth/thetvdb) [![Latest Unstable Version](https://camo.githubusercontent.com/0e2a856628fdf226ecfef0a51949140e7afbf80b6adc23f8c0e53ab412d21a55/68747470733a2f2f706f7365722e707567782e6f72672f616472656e74682f746865747664622f762f756e737461626c65)](https://packagist.org/packages/adrenth/thetvdb) [![License](https://camo.githubusercontent.com/0c465b77d85d8e5cfc5cf83e9ed9561ebf88d83b1bdd7d87b52e8c704ebdcc16/68747470733a2f2f706f7365722e707567782e6f72672f616472656e74682f746865747664622f6c6963656e7365)](https://packagist.org/packages/adrenth/thetvdb)[![SensioLabsInsight](https://camo.githubusercontent.com/676331d285f99ca697da231148ef03793e9c0a772e8feada15c5ee1e8cdfe78a/68747470733a2f2f696e73696768742e73656e73696f6c6162732e636f6d2f70726f6a656374732f63353735666435622d306261612d346562312d616434642d3861623566623230626139632f6d696e692e706e67)](https://insight.sensiolabs.com/projects/c575fd5b-0baa-4eb1-ad4d-8ab5fb20ba9c)

This is an API client for the thetvdb.com website. It's using the XML feeds that are publicly available.

API Key Registration
--------------------

[](#api-key-registration)

To use this PHP package, you need to request an API Key from the thetvdb.com website: .

Please follow these guidelines:

- If you will be using the API information in a commercial product or website, you must email  and wait for authorization before using the API. However, you MAY use the API for development and testing before a public release.
- If you have a publicly available program, you MUST inform your users of this website and request that they help contribute information and artwork if possible.
- You MUST familiarize yourself with our data structure, which is detailed in the wiki documentation.
- You MUST NOT perform more requests than are necessary for each user. This means no downloading all of our content (we'll provide the database if you need it). Play nice with our server.
- You MUST NOT directly access our data without using the documented API methods.
- You MUST keep the email address in your account information current and accurate in case we need to contact you regarding your key (we hate spam as much as anyone, so we'll never release your email address to anyone else).
- Please feel free to contact us and request changes to our site and/or API. We'll happily consider all reasonable suggestions.

*Source: thetvdb.com*

API v2
------

[](#api-v2)

There is also a version 2 of the API for which I also created a PHP client. See https://github.com/adrenth/thetvdb2.

Installation
------------

[](#installation)

Install this package using composer:

```
$ composer require adrenth/thetvdb

```

Usage
-----

[](#usage)

Create a Client instance:

```
$apiKey = 'yourapikey';
$cache = new \Doctrine\Common\Cache\FilesystemCache('path/to/cache');
$client = new Client($cache, $apiKey);

```

### Cache

[](#cache)

```
$client->setCacheTtl(3600); // in seconds

```

### Language

[](#language)

```
$language = new Language('nl');

echo $language->getCode();
// 'nl'
echo $language->getLabel();
// 'Nederlands'

$language = $client->getUserPreferredLanguage($accountId);

```

#### Managing User Ratings

[](#managing-user-ratings)

```
// Returns a UserFavoritesResponse
$favorites = $client->getUserFavorites($accountId);
$seriesIds = $favorites->getSeriesIds();

$favorites = $client->addUserFavorite($accountId, $seriesId);
$seriesIds = $favorites->getSeriesIds();

$favorites = $client->removeUserFavorite($accountId, $seriesId);
$seriesIds = $favorites->getSeriesIds();

```

#### Managing User Ratings

[](#managing-user-ratings-1)

```
$rating = $client->addUserRatingForEpisode($accountId, $episodeId, $rating);
$rating = $client->removeUserRatingForEpisode($accountId, $episodeId);
$rating = $client->addUserRatingForSeries($accountId, $seriesId, $rating);
$rating = $client->removeUserRatingForSeries($accountId, $seriesId);

echo $rating->getUserRating();
// 7
echo $rating->getCommunityRating();
// 7.65

```

#### Searching / Fetching Series

[](#searching--fetching-series)

```
$language = new Language('nl');
$response = $client->getSeries('Ray Donovan', $language, $accountId);
$seriesCollection = $response->getSeries();

foreach ($seriesCollection as $series) {
	echo $series->getName();
}

$response = $client->getSeriesByImdbId('tt0290978');
$response = $client->getSeriesByImdbId('tt0290978', new \Adrenth\Thetvdb\Language('de'));
$response = $client->getSeriesByZap2itId('EP01579745', new \Adrenth\Thetvdb\Language('nl'));

```

Caching
-------

[](#caching)

This package requires a Doctrine `Cache` instance. To disable caching (which I will never recommend!) just provide a `VoidCache` or `ArrayCache` instance.

For more information about Doctrine Cache visit

Contributing
------------

[](#contributing)

Please contribute to make this package even better.

###  Health Score

27

—

LowBetter than 47% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor2

2 contributors hold 50%+ of commits

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 ~19 days

Recently: every ~32 days

Total

9

Last Release

3771d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c38e829966665f64fa8cbac286c5e6e381094646241a5a8489d1e84d1b29b31b?d=identicon)[adrenth](/maintainers/adrenth)

---

Top Contributors

[![adrenth](https://avatars.githubusercontent.com/u/5699988?v=4)](https://github.com/adrenth "adrenth (6 commits)")[![Erliz](https://avatars.githubusercontent.com/u/1262276?v=4)](https://github.com/Erliz "Erliz (5 commits)")[![rdrenth](https://avatars.githubusercontent.com/u/3629317?v=4)](https://github.com/rdrenth "rdrenth (4 commits)")

---

Tags

apiapi-clientphpthetvdbapilibrarythetvdb.comthetvdb

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/adrenth-thetvdb/health.svg)

```
[![Health](https://phpackages.com/badges/adrenth-thetvdb/health.svg)](https://phpackages.com/packages/adrenth-thetvdb)
```

###  Alternatives

[craftcms/cms

Craft CMS

3.6k3.6M2.9k](/packages/craftcms-cms)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3661.2M46](/packages/tencentcloud-tencentcloud-sdk-php)[checkout/checkout-sdk-php

Checkout.com SDK for PHP

563.5M10](/packages/checkout-checkout-sdk-php)[fschmtt/keycloak-rest-api-client-php

PHP client to interact with Keycloak's Admin REST API.

48100.6k2](/packages/fschmtt-keycloak-rest-api-client-php)[files.com/files-php-sdk

Files.com PHP SDK

2478.1k](/packages/filescom-files-php-sdk)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

232.5k](/packages/eslazarev-wildberries-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)