PHPackages                             mfonte/imdb-scraper - 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. mfonte/imdb-scraper

ActivePackage[API Development](/categories/api)

mfonte/imdb-scraper
===================

Locale-Aware PHP IMDb Scraper, with a fluent API for searching for Movies and TV Shows, and retrieving detailed information about them.

v2.0.6(6mo ago)1683[1 issues](https://github.com/mauriziofonte/imdb-scraper/issues)Apache-2.0PHPPHP >=8.1

Since Jun 12Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/mauriziofonte/imdb-scraper)[ Packagist](https://packagist.org/packages/mfonte/imdb-scraper)[ RSS](/packages/mfonte-imdb-scraper/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (7)Versions (6)Used By (0)

Mfonte IMDb Scraper
===================

[](#mfonte-imdb-scraper)

A **PHP library** for scraping movie and TV show data from IMDb with ease. This package provides methods to retrieve detailed information about movies and TV shows using best matches or strict year-based queries, **with support for localized searches**.

Caution

This package is intended for educational and personal use only. Users are responsible for ensuring their use complies with IMDb's Terms of Service and applicable laws. The author does not condone or encourage unauthorized scraping or other activities that violate legal agreements. Please, refer to the [IMDb Conditions of Use](https://www.imdb.com/conditions?utm_source) for more information. **It is your sole responsibility to use this package in compliance with IMDb's Terms of Service.**

List of supported locales
-------------------------

[](#list-of-supported-locales)

- English (`en-US`) via `en`
- Italian (`it-IT`) via `it`
- Spanish (`es-ES`) via `es`
- French (`fr-FR`) via `fr`
- German (`de-DE`) via `de`
- Portuguese (`pt-BR`) via `pt`
- Indian (`hi-IN`) via `hi`

---

Overview
--------

[](#overview)

Mfonte IMDb Scraper is a lightweight, object-oriented library to interact with IMDb. It provides functionalities to:

- Retrieve movie and TV show details by title and year, or IMDb ID, **with robust exception handling**, with support for **multiple locales**.
- Fetch data like plot, actors, genres, ratings, and similar titles.
- Narrow results using "best match" algorithms or strict filters.

Key features include:

- **Localized searches** using the `locale` option.
- Built-in **caching** for optimized performance.
- `v2` tag works from **PHP 8.1** onwards. `v1` tag Works from **PHP 7.3** to **PHP 8.0**.

---

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Usage](#usage)
    - [Basic Example](#basic-example)
    - [The `Title` Object](#the-title-object)
    - [Options](#options)
    - [Methods](#methods)
        - [Best Match Overview](#best-match-overview)
        - [By Year Overview](#by-year-overview)
        - [Handling Exceptions](#handling-exceptions)
        - [The `id()` Method](#the-id-method)
        - [The `search()` Method](#the-search-method)
- [Summary of Exceptions and Methods](#summary-of-exceptions-and-methods)
- [Advanced Features](#advanced-features)
    - [Caching](#caching)
    - [Locale](#locale)
- [Contributing](#contributing)
- [License](#license)

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

[](#installation)

Release tag `v1` is compatible with PHP versions `7.3`, `7.4` and `8.0` (monolog `^2.0`).

Install the package via Composer:

```
composer require mfonte/imdb-scraper "^1.0"
```

Release tag `v2` is compatible with PHP versions `8.1`, `8.2`, `8.3`, `8.4` (monolog `^3.0`).

Install the package via Composer:

```
composer require mfonte/imdb-scraper "^2.0"
```

---

Usage
-----

[](#usage)

### Basic Example

[](#basic-example)

```
use Mfonte\ImdbScraper\Imdb;
use Mfonte\ImdbScraper\Exceptions\NoSearchResults;
use Mfonte\ImdbScraper\Exceptions\MultipleSearchResults;

// Create an IMDb scraper instance
$imdb = Imdb::new(['locale' => 'en']);

// Fetch movie details using best match
$movie = $imdb->movie('The Godfather');

// Output some details
echo $movie->title;  // The Godfather
echo $movie->year;   // 1972
echo $movie->plot;   // "The aging patriarch of an organized crime dynasty transfers control..."

// When using movie(), tvSeries(), movieByYear(), or tvSeriesByYear(), catch exceptions!
try {
    $movie = $imdb->movie('The Godfather');
} catch (NoSearchResults $e) {
    echo 'No results found!';
} catch (MultipleSearchResults $e) {
    echo 'Multiple results found!';
}

// you can also fetch a Title by its IMDB ID
$item = $imdb->id('tt0068646');
echo $item->title;  // The Godfather

// you can also only search for results
$results = $imdb->search('godfather');
```

All methods return a `Mfonte\ImdbScraper\Title` object with the following properties.

### The `Title` Object

[](#the-title-object)

The `Title` object represents detailed information about a movie or TV show fetched using the `ImdbScraper` library. It encapsulates all key attributes of a title, including metadata, cast, genres, and links to related content.

#### Properties of the `Title` Object

[](#properties-of-the-title-object)

**Property****Type****Description****`id`**`string`The unique IMDb ID of the title (e.g., `"tt1234567"`).**`isTvSeries`**`bool`Indicates whether the title is a TV series (`true`) or a movie (`false`).**`link`**`string`The URL of the IMDb page for the title.**`title`**`string`The official title of the movie or TV show.**`originalTitle`**`string`The original title of the movie or TV show.**`year`**`intnull`**`length`**`stringnull`**`rating`**`floatnull`**`ratingVotes`**`intnull`**`popularityScore`**`intnull`**`metaScore`**`intnull`**`genres`**`array`A list of genres associated with the title (e.g., `["Action", "Drama"]`).**`posterUrl`**`stringnull`**`trailerUrl`**`stringnull`**`plot`**`stringnull`**`actors`**`Dataset`A dataset containing the cast members of the title. (`Person` objects)**`similars`**`Dataset`A dataset containing similar titles to the one fetched. (`Title` objects)**`seasonRefs`**`array`A list of season numbers for a TV series (e.g., `[1, 2, 3, 4]`).**`seasons`**`Dataset`A dataset containing detailed information about seasons for a TV series. (`Season` objects)**`credits`**`Dataset`A dataset containing all credits associated with the title, including directors, writers, and producers. (`Credit` objects)**`metadata`**`array`Raw metadata associated with the title.---

Options
-------

[](#options)

The scraper provides various configuration options during initialization:

OptionDefaultDescription`cache``false`Enables caching of results.`locale``en`Sets the locale for searches (e.g., `it` for Italian).`seasons``false`If `true`, fetches season data for TV shows.`credits``false`If `true`, fetches detailed credits information.`guzzleLogFile``null`File path for logging HTTP requests (useful for debugging).### Example: Setting Options

[](#example-setting-options)

```
use Mfonte\ImdbScraper\Imdb;

// Enable caching and use Italian locale
$imdb = Imdb::new([
    'cache' => true,
    'locale' => 'it'
]);

// Fetch a localized movie
$movie = $imdb->movie('La ricerca della felicità');
echo $movie->title;  // La ricerca della felicità
```

---

Methods
-------

[](#methods)

### Best Match Overview

[](#best-match-overview)

The `movie()` and `tvSeries()` methods find the best match for a given title. The library uses a **Levenshtein algorithm** to rank results and selects the closest match.

#### Example with `movie()`

[](#example-with-movie)

```
use Mfonte\ImdbScraper\Imdb;

// Fetch the best match for a movie title
$movie = Imdb::new()->movie('godfather');
echo $movie->id;       // tt0068646
echo $movie->title;    // The Godfather
echo $movie->year;     // 1972
```

---

### By Year Overview

[](#by-year-overview)

The `movieByYear()` and `tvSeriesByYear()` methods perform a strict search for titles matching the specified year. If no exact match is found, the library checks for movies released one year before or after the given year.

#### Example with `movieByYear()`

[](#example-with-moviebyyear)

```
use Mfonte\ImdbScraper\Imdb;

// Fetch a movie by title and year
$movie = Imdb::new()->movieByYear('from dusk dawn', 1996);
echo $movie->id;       // tt0116367
echo $movie->title;    // From Dusk Till Dawn
echo $movie->year;     // 1996
```

---

Handling Exceptions
-------------------

[](#handling-exceptions)

The methods `movie()`, `tvSeries()`, `movieByYear()`, and `tvSeriesByYear()` in the `Imdb` class throw exceptions when specific conditions are not met during the search:

1. **`NoSearchResults` Exception**:

    - Thrown when no results are found for the provided query.
    - Example:

        ```
        use Mfonte\ImdbScraper\Imdb;
        use Mfonte\ImdbScraper\Exceptions\NoSearchResults;

        $imdb = Imdb::new(['locale' => 'en']);

        try {
            $movie = $imdb->movie('nonexistent title');
        } catch (NoSearchResults $e) {
            echo 'No results found for the query.';
        }
        ```
2. **`MultipleSearchResults` Exception**:

    - Thrown when the query returns multiple results but the method cannot narrow them down to a single title.
    - Example:

        ```
        use Mfonte\ImdbScraper\Imdb;
        use Mfonte\ImdbScraper\Exceptions\MultipleSearchResults;

        $imdb = Imdb::new(['locale' => 'en']);

        try {
            $movie = $imdb->movie('godfather');
        } catch (MultipleSearchResults $e) {
            echo 'Multiple results found for the query.';
        }
        ```
3. **`BadMethodCall` Exception**:

    - Thrown when invalid input is provided to the `id()` method or other API methods.
    - Example:

        ```
        use Mfonte\ImdbScraper\Imdb;
        use Mfonte\ImdbScraper\Exceptions\BadMethodCall;

        $imdb = Imdb::new(['locale' => 'en']);

        try {
            $movie = $imdb->id('invalid_id');
        } catch (BadMethodCall $e) {
            echo 'Invalid IMDb ID provided.';
        }
        ```

---

The `id()` Method
-----------------

[](#the-id-method)

The `id()` method allows you to fetch detailed information about a movie or TV show using its unique IMDb ID.

```
use Mfonte\ImdbScraper\Imdb;

$imdb = Imdb::new(['locale' => 'en']);

$movie = $imdb->id('tt0110912'); // Pulp Fiction IMDb ID

echo $movie->title;  // Pulp Fiction
echo $movie->year;   // 1994
```

**Key Features**:

- Accepts only valid IMDb IDs in the format `tt1234567`.
- Throws a `BadMethodCall` exception if the input is invalid.

---

The `search()` Method
---------------------

[](#the-search-method)

The `search()` method performs a general search query and returns a `Dataset` containing `SearchResult` objects for all matches.

```
use Mfonte\ImdbScraper\Imdb;

$imdb = Imdb::new(['locale' => 'en']);

$results = $imdb->search('godfather');
foreach ($results as $result) {
    echo $result->title . " (" . $result->year . ")" . PHP_EOL;
}
```

**Key Features**:

- Returns a `Dataset` of `SearchResult` objects.
- Each `SearchResult` includes fields like `id`, `title`, `year`, `type`, and more.

---

Summary of Exceptions and Methods
---------------------------------

[](#summary-of-exceptions-and-methods)

**Method****Description****Exceptions Thrown**`movie($title)`Fetches the best match for a movie title.`NoSearchResults`, `MultipleSearchResults``tvSeries($title)`Fetches the best match for a TV series title.`NoSearchResults`, `MultipleSearchResults``movieByYear($title, $year)`Fetches a movie by title and year.`NoSearchResults`, `MultipleSearchResults``tvSeriesByYear($title, $year)`Fetches a TV series by title and year.`NoSearchResults`, `MultipleSearchResults``id($imdbId)`Fetches a movie or TV show by IMDb ID (e.g., `tt1234567`).`BadMethodCall``search($query)`Performs a general search and returns a `Dataset` of `SearchResult` objects.-With these robust exception-handling mechanisms and versatile methods, the `Imdb` class offers both flexibility and reliability for your IMDb scraping needs.

Advanced Features
-----------------

[](#advanced-features)

### Caching

[](#caching)

Enable caching for faster repeated lookups. Cache works seamlessly and stores results locally.

```
$imdb = Imdb::new(['cache' => true]);
$movie = $imdb->movie('Inception');
```

### Locale

[](#locale)

Retrieve localized movie titles, plots, and other data by setting the `locale` option.

```
$imdb = Imdb::new(['locale' => 'it']);
$movie = $imdb->movie('Pursuit Happyness');
echo $movie->title;  // La ricerca della felicità
```

---

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

[](#contributing)

Contributions are welcome! Feel free to open an issue or submit a pull request.

---

License
-------

[](#license)

This project is licensed under the MIT License. See the LICENSE file for details.

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance47

Moderate activity, may be stable

Popularity14

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~49 days

Total

4

Last Release

191d ago

Major Versions

v1.0.4 → v2.0.52025-09-03

PHP version history (2 changes)v2.0.4PHP >=8.1

v1.0.4PHP >=7.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/7733524e324e4a6f68d80bad3cfc5737cda0bfb072154210de09c7c2820d070c?d=identicon)[mauriziofonte](/maintainers/mauriziofonte)

---

Top Contributors

[![mauriziofonte](https://avatars.githubusercontent.com/u/1758841?v=4)](https://github.com/mauriziofonte "mauriziofonte (14 commits)")

---

Tags

apisearchmovieimdbfilm

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mfonte-imdb-scraper/health.svg)

```
[![Health](https://phpackages.com/badges/mfonte-imdb-scraper/health.svg)](https://phpackages.com/packages/mfonte-imdb-scraper)
```

###  Alternatives

[algolia/algoliasearch-client-php

API powering the features of Algolia.

69333.0M114](/packages/algolia-algoliasearch-client-php)[hmerritt/imdb-api

IMDB API that can fetch film data and search results

6911.3k](/packages/hmerritt-imdb-api)[php-tmdb/laravel

Laravel Package for TMDB ( The Movie Database ) API. Provides easy access to the wtfzdotnet/php-tmdb-api library.

16553.3k1](/packages/php-tmdb-laravel)[wtfzdotnet/php-tmdb-api

PHP wrapper for TMDB (TheMovieDatabase) API v3. Supports two types of approaches, one modelled with repositories, models and factories. And the other by simple array access to RAW data from The Movie Database.

4282.9k](/packages/wtfzdotnet-php-tmdb-api)[gigablah/fsphinxphp

Facet extension for Sphinx Search

5362.8k](/packages/gigablah-fsphinxphp)[php-tmdb/symfony

Symfony Bundle for TMDB (The Movie Database) API. Provides easy access to the php-tmdb/api library.

3649.7k](/packages/php-tmdb-symfony)

PHPackages © 2026

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