PHPackages                             canihavesomecoffee/thetvdbapi - 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. canihavesomecoffee/thetvdbapi

ActiveLibrary[API Development](/categories/api)

canihavesomecoffee/thetvdbapi
=============================

PHP implementation for the 4th version of the TheTVDb API.

2.1.12(5mo ago)1021.0k↓25.9%10[1 issues](https://github.com/canihavesomecoffee/theTVDbAPI/issues)[3 PRs](https://github.com/canihavesomecoffee/theTVDbAPI/pulls)1ISCPHPPHP >=7.4CI passing

Since Sep 9Pushed 5mo ago2 watchersCompare

[ Source](https://github.com/canihavesomecoffee/theTVDbAPI)[ Packagist](https://packagist.org/packages/canihavesomecoffee/thetvdbapi)[ RSS](/packages/canihavesomecoffee-thetvdbapi/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (64)Used By (1)

CanIHaveSomeCoffee/TheTVDbAPI
=============================

[](#canihavesomecoffeethetvdbapi)

[![Packagist](https://camo.githubusercontent.com/6f598e7b395ed67eee2e7233395d369ecea50a19af9722db4820a9672737781f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f63616e6968617665736f6d65636f666665652f746865747664626170692e737667)](https://packagist.org/packages/canihavesomecoffee/thetvdbapi)[![Minimum PHP Version](https://camo.githubusercontent.com/49fff3d85b16b263aaec76c1dfd2e46d04442507f6dc55fb3403db167d0ea1e5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f63616e6968617665736f6d65636f666665652f74686554564462415049)](https://php.net/)[![Build status](https://camo.githubusercontent.com/7505c8cfdec9c6554aa84b1b6a7b9048b231739bf6bc5b08ea0b9ab28221ba2a/68747470733a2f2f6170692e7472617669732d63692e6f72672f63616e6968617665736f6d65636f666665652f746865545644624150492e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/canihavesomecoffee/theTVDbAPI)[![codecov](https://camo.githubusercontent.com/f901cbc01859aaec86e657ed7e52d63657b16f8ae60aa95edf984bf406025b26/68747470733a2f2f636f6465636f762e696f2f67682f63616e6968617665736f6d65636f666665652f746865545644624150492f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/canihavesomecoffee/theTVDbAPI)

This is an API client for the thetvdb.com website. It's using the **4th** version of the theTVDb API. In order to be able to access this API you'll have to register on theTVDb first and obtain a project key.

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

[](#api-key-registration)

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

> We have two models for API access, both that provide funding that allows us to continue running and improving the site. The first is our negotiated license model, which allows commercial companies to negotiate access with us. The second is a user-subscription model, which allows end users to access the API if they are subscribed. We reserve the right to change our interfaces, fees, or licensing terms at any point without notice.

To create an API key, create an account and visit the API keys page on your dashboard.

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

[](#installation)

Install this package using composer:

```
$ composer require canihavesomecoffee/thetvdbapi

```

Documentation
-------------

[](#documentation)

The official API documentation can be found here: https://thetvdb.github.io/v4-api/.

For usage examples of the API, please refer to the examples' folder.

### API-wide translations

[](#api-wide-translations)

You can pass a primary and secondary (fallback) language to the API constructor.

For example, if you want translations in Dutch, but a fallback to English if no Dutch translations exist, you can set this as follows:

```
$theTVDbAPI = new \CanIHaveSomeCoffee\TheTVDbAPI\TheTVDbAPI("nld", "eng");

```

By default, the primary language is set to English without a fallback language.

### Authentication

[](#authentication)

```
$theTVDbAPI = new \CanIHaveSomeCoffee\TheTVDbAPI\TheTVDbAPI();

// Obtain a token. Optionally you can pass a user pin through as well.
$token = $theTVDbAPI->authentication()->login($apiKey);

// Set the token
$theTVDbAPI->setToken($token);

```

### Routes

[](#routes)

The `TheTVDbAPI` offers access to the same routes that the API provides. A few usage examples are listed below:

#### Authentication

[](#authentication-1)

```
$theTVDbAPI->authentication()->login($apiKey);
// or in case it's a project with user-specific subscriptions
$theTVDbAPI->authentication()->login($apiKey, $pin);

```

#### Languages

[](#languages)

```
$theTVDbAPI->languages()->all();

```

#### Episodes

[](#episodes)

```
$theTVDbAPI->episodes()->simple(6347388);
$theTVDbAPI->episodes()->extended(8366715);
$theTVDbAPI->episodes()->translations(8366715, "nld");

```

#### Series

[](#series)

```
$theTVDbAPI->series()->list();
$theTVDbAPI->series()->simple(280258);
$theTVDbAPI->series()->extended(280258);
$theTVDbAPI->series()->translate(280258);
$theTVDbAPI->series()->episodes(280258); // Paginated
$theTVDbAPI->series()->allEpisodes(280258); // All episodes, translated

```

#### Search

[](#search)

```
$theTVDbAPI->search()->search("Ideale");
$theTVDbAPI->search()->search("Ideale", ["year" => 2014]);
$theTVDbAPI->search()->search("Ideale Wereld", ["type" => "series"]);

```

#### Updates

[](#updates)

Fetch a list of entities that have been recently updated:

```
$now = new DateTime();
$now->sub(new DateInterval("PT2H"));
$theTVDbAPI->updates()->query($now);

```

Some wrapper methods are available to restrict results:

```
$now = new DateTime();
$now->sub(new DateInterval("PT2H"));
$theTVDbAPI->updates()->fetchSerieUpdates($now);
$theTVDbAPI->updates()->fetchEpisodeUpdates($now);

```

#### Artwork

[](#artwork)

```
$theTVDbAPI->artwork()->simple(62001533);
$theTVDbAPI->artwork()->extended(62001533);
$theTVDbAPI->artwork()->statuses();
$theTVDbAPI->artwork()->types();

```

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

[](#contributing)

While the aim is to provide a ready-to-use API, it's possible that things are missing or outdated. If you think something is missing, or you want to add something, feel free to open up an issue, or even better, make a Pull Request (PR) with a fix or improvement. The PR's will be gladly accepted in order to improve this client API.

###  Health Score

55

—

FairBetter than 98% of packages

Maintenance71

Regular maintenance activity

Popularity36

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 88.9% 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 ~51 days

Recently: every ~253 days

Total

60

Last Release

152d ago

Major Versions

1.3.0 → 2.0.0.beta2021-05-02

PHP version history (3 changes)1.0.0PHP >=7.1

1.1.0PHP >=7.2

2.0.0.betaPHP >=7.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/1b230af8bd941e3b7c5af9e2e8c6016bec69f1697358e90a5d4b90fe3b4d3df1?d=identicon)[canihavesomecoffee](/maintainers/canihavesomecoffee)

---

Top Contributors

[![canihavesomecoffee](https://avatars.githubusercontent.com/u/7365586?v=4)](https://github.com/canihavesomecoffee "canihavesomecoffee (136 commits)")[![CicerBro](https://avatars.githubusercontent.com/u/177757655?v=4)](https://github.com/CicerBro "CicerBro (8 commits)")[![DariusIII](https://avatars.githubusercontent.com/u/3399658?v=4)](https://github.com/DariusIII "DariusIII (4 commits)")[![dependabot-preview[bot]](https://avatars.githubusercontent.com/in/2141?v=4)](https://github.com/dependabot-preview[bot] "dependabot-preview[bot] (4 commits)")[![tntsoft](https://avatars.githubusercontent.com/u/5844176?v=4)](https://github.com/tntsoft "tntsoft (1 commits)")

---

Tags

apiapi-clientapi-wrapperhacktoberfestphpthetvdbthetvdb-api

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/canihavesomecoffee-thetvdbapi/health.svg)

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

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[craftcms/cms

Craft CMS

3.6k3.6M2.6k](/packages/craftcms-cms)[googleads/googleads-php-lib

Google Ad Manager SOAP API Client Library for PHP

67410.3M25](/packages/googleads-googleads-php-lib)[api-platform/symfony

Symfony API Platform integration

323.2M67](/packages/api-platform-symfony)[web-auth/webauthn-framework

FIDO2/Webauthn library for PHP and Symfony Bundle.

50570.7k1](/packages/web-auth-webauthn-framework)[api-platform/serializer

API Platform core Serializer

223.4M31](/packages/api-platform-serializer)

PHPackages © 2026

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