PHPackages                             zero-to-prod/omdb-api - 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. zero-to-prod/omdb-api

ActiveLibrary[API Development](/categories/api)

zero-to-prod/omdb-api
=====================

A cURL wrapper for the OMDb API

v1.0.7(1y ago)11.3k3MITPHPPHP >=7.1.0CI passing

Since Dec 31Pushed 1y ago1 watchersCompare

[ Source](https://github.com/zero-to-prod/omdb-api)[ Packagist](https://packagist.org/packages/zero-to-prod/omdb-api)[ Docs](https://github.com/zero-to-prod/omdb-api)[ Fund](https://github.com/sponsors/zero-to-prod)[ RSS](/packages/zero-to-prod-omdb-api/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (5)Dependencies (1)Versions (6)Used By (3)

Zerotoprod\\OmdbApi
===================

[](#zerotoprodomdbapi)

[![](art/logo.png)](art/logo.png)

[![Repo](https://camo.githubusercontent.com/9a90a3efeee26aed7d7f2feee9cd84566a26f9c362cc773b184d076210906e1c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6769746875622d677261793f6c6f676f3d676974687562)](https://github.com/zero-to-prod/omdb-api)[![GitHub Actions Workflow Status](https://camo.githubusercontent.com/8903c4f524c0cfd7cf081a3de6e95b7c66f30b57f1cb1155d534020166d9d566/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7a65726f2d746f2d70726f642f6f6d64622d6170692f746573742e796d6c3f6c6162656c3d74657374)](https://github.com/zero-to-prod/omdb-api/actions)[![Packagist Downloads](https://camo.githubusercontent.com/0887543faa4c643616fea4fea3a9328ec7982f2350321c16cdbe76857db25aac/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7a65726f2d746f2d70726f642f6f6d64622d6170693f636f6c6f723d626c7565)](https://packagist.org/packages/zero-to-prod/omdb-api/stats)[![Packagist Version](https://camo.githubusercontent.com/ba25ee3fd034c4069a52daa477bad3aa63f253cabbea6b21c643e85bfc1ba4a0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a65726f2d746f2d70726f642f6f6d64622d6170693f636f6c6f723d663238643161)](https://packagist.org/packages/zero-to-prod/omdb-api)[![License](https://camo.githubusercontent.com/ce3f533c1564c97ae05c5e68022e22f5cabea2dbad79d2d22c5f1cd1dd7d501b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7a65726f2d746f2d70726f642f6f6d64622d6170693f636f6c6f723d726564)](https://github.com/zero-to-prod/omdb-api/blob/main/LICENSE.md)[![wakatime](https://camo.githubusercontent.com/346aedba7b09597f3413b6f6d420aae94446f94dd617586409f4beadb38651ee/68747470733a2f2f77616b6174696d652e636f6d2f62616467652f6769746875622f7a65726f2d746f2d70726f642f6f6d64622d6170692e737667)](https://wakatime.com/badge/github/zero-to-prod/omdb-api)[![Hits-of-Code](https://camo.githubusercontent.com/f3985118c3b603b48b917eb48109103ef8f4523a090571cf3aa43acb60233dd4/68747470733a2f2f686974736f66636f64652e636f6d2f6769746875622f7a65726f2d746f2d70726f642f6f6d64622d6170693f6272616e63683d6d61696e)](https://hitsofcode.com/github/zero-to-prod/omdb-api/view?branch=main)

Contents
--------

[](#contents)

- [Introduction](#introduction)
- [TLDR](#tldr)
- [Requirements](#requirements)
    - [Getting an OMDb API Key](#getting-an-omdb-api-key)
- [Installation](#installation)
- [Usage](#usage)
- [Methods Overview](#methods-overview)
    - [byIdOrTitle()](#byidortitle)
    - [search()](#search)
    - [poster()](#poster)
- [Error Handling](#error-handling)
- [Local Development](./LOCAL_DEVELOPMENT.md)
- [Contributing](#contributing)

Introduction
------------

[](#introduction)

`Zerotoprod\OmdbApi` is a PHP cURL wrapper for the [OMDb API](https://www.omdbapi.com/). It allows you to search for movies, series, and other media, retrieve detailed information using IMDb IDs or titles, and fetch poster images.

TLDR
----

[](#tldr)

```
use Zerotoprod\OmdbApi\OmdbApi;

$OmdbApi = new OmdbApi('apiKey');

// Find a title by ImdbID (Internet Movie DataBase ID) or title
$OmdbApi->byIdOrTitle('Avatar')['Title']; // 2009

// Find multiple titles
$OmdbApi->search('Avatar')['Search'][0]['Year']; // 2009

// Get the poster art of a title by its ImdbID
$OmdbApi->poster('tt0499549'); // https://img.omdbapi.com/?apikey=8f8423aa&i=tt0499549
```

Requirements
------------

[](#requirements)

- PHP 8.1 or higher.
- cURL extension enabled (typically enabled by default in most PHP installations).
- A valid [OMDb API key](https://www.omdbapi.com/apikey.aspx). A free key is typically available.

### Getting an OMDb API Key

[](#getting-an-omdb-api-key)

1. Go to the [OMDb API website](https://www.omdbapi.com/apikey.aspx).
2. Sign up for a free or paid plan depending on your usage requirements.
3. After registering, you will receive an API Key that you must pass to the OmdbApi class during initialization.

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

[](#installation)

Install `Zerotoprod\OmdbApi` via [Composer](https://getcomposer.org/):

```
composer require zero-to-prod/omdb-api
```

This will add the package to your project’s dependencies and create an autoloader entry for it.

Usage
-----

[](#usage)

Initialization

```
use Zerotoprod\OmdbApi\OmdbApi;

$OmdbApi = new OmdbApi('apiKey');
```

You can also customize the base URL and the poster URL if you need to (for example, to proxy through another service):

```
$OmdbApi = new OmdbApi(
    apikey: 'your-omdb-api-key',
    base_url: 'https://www.omdbapi.com/',
    img_url: 'https://img.omdbapi.com/'
);
```

Methods Overview
----------------

[](#methods-overview)

Below is a summary of the primary methods exposed by this package:

### `byIdOrTitle()`

[](#byidortitle)

Retrieve detailed information about a specific movie, TV series, or episode by either its IMDb ID or title.

```
public function byIdOrTitle(
    ?string $title = null,      // (optional): A string containing the title to look up (e.g. “Avatar”)
    ?string $imdbID = null,     // (optional): A valid IMDb ID (e.g. “tt1285016”)
    ?string $type = null,       // (optional): The type of media to search for. Acceptable values are “movie”, “series”, "game", or “episode”.
    ?int    $year = null,       // (optional): Year of release
    ?bool   $full_plot = false, // (optional): If true, returns the full plot instead of a short summary
    mixed   $callback = null,   // (optional): JSONP callback name (if needed).
    ?string $version = null,    // (optional): Reserved for future use.
    ?array  $CURLOPT = [CURLOPT_TIMEOUT => 10] // An associative array of [cURL options](https://www.php.net/manual/en/function.curl-setopt.php). Defaults to [CURLOPT_TIMEOUT => 10].
): array
```

Returns an [error](#error-handling) or this response:

```
[
  "Title" => "Avatar",
  "Year" => "2009",
  "Rated" => "PG-13",
  "Released" => "18 Dec 2009",
  "Runtime" => "162 min",
  "Genre" => "Action, Adventure, Fantasy",
  "Director" => "James Cameron",
  "Writer" => "James Cameron",
  "Actors" => "Sam Worthington, Zoe Saldana, Sigourney Weaver",
  "Plot" => "A paraplegic Marine dispatched to the moon Pandora on a unique mission becomes torn between following his orders and protecting the world he feels is his home.",
  "Language" => "English, Spanish",
  "Country" => "United States, United Kingdom",
  "Awards" => "Won 3 Oscars. 91 wins & 131 nominations total",
  "Poster" => "https://m.media-amazon.com/images/M/MV5BMDEzMmQwZjctZWU2My00MWNlLWE0NjItMDJlYTRlNGJiZjcyXkEyXkFqcGc@._V1_SX300.jpg",
  "Ratings" => [
    [
      "Source" => "Internet Movie Database",
      "Value" => "7.9/10"
    ],
    [
      "Source" => "Rotten Tomatoes",
      "Value" => "81%"
    ],
    [
      "Source" => "Metacritic",
      "Value" => "83/100"
    ]
  ],
  "Metascore" => "83",
  "imdbRating" => "7.9",
  "imdbVotes" => "1,411,534",
  "imdbID" => "tt0499549",
  "Type" => "movie",
  "DVD" => "N/A",
  "BoxOffice" => "$785,221,649",
  "Production" => "N/A",
  "Website" => "N/A",
  "Response" => "True"
];
```

### `search()`

[](#search)

Search for multiple titles using a keyword.

```
public function search(
    string $title,          // (required): A string representing the search term (e.g. “Avatar”)
    ?string $type = null,   // (optional): “movie”, “series”, or “episode”
    ?int $year = null,      // Year of release to narrow down results
    ?int $page = 1,         // (optional): Page number for paginated results
    mixed $callback = null, // (optional): JSONP callback name
    ?string $version = null,// (optional): Reserved for future use
    ?array $CURLOPT = [CURLOPT_TIMEOUT => 10] // An associative array of [cURL options](https://www.php.net/manual/en/function.curl-setopt.php). Defaults to [CURLOPT_TIMEOUT => 10].
): array
```

Returns an [error](#error-handling) or this response:

```
[
  "Search" => [
    [
      "Title" => "Avatar",
      "Year" => "2009",
      "imdbID" => "tt0499549",
      "Type" => "movie",
      "Poster" => "https://m.media-amazon.com/images/M/MV5BMDEzMmQwZjctZWU2My00MWNlLWE0NjItMDJlYTRlNGJiZjcyXkEyXkFqcGc@._V1_SX300.jpg"
    ],
    [
      "Title" => "Avatar: The Way of Water",
      "Year" => "2022",
      "imdbID" => "tt1630029",
      "Type" => "movie",
      "Poster" => "https://m.media-amazon.com/images/M/MV5BNmQxNjZlZTctMWJiMC00NGMxLWJjNTctNTFiNjA1Njk3ZDQ5XkEyXkFqcGc@._V1_SX300.jpg"
    ]
  ],
  "totalResults" => "113",
  "Response" => "True"
];
```

### `poster()`

[](#poster)

Get the direct URL to the poster image for a given IMDb ID.

```
$OmdbApi->poster('tt0499549'); // https://img.omdbapi.com/?apikey=8f8423aa&i=tt0499549
```

### Error Handling

[](#error-handling)

When a request fails (for example, if no matching title is found, cURL fails to initialize, or an invalid response comes back), the returned array includes:

```
[
    'ErrorType' => 'validation' | 'curl' | 'server',
    'message'   => 'A descriptive message about the error.',
    'extra'     => [...optional additional data...]
]
```

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

[](#contributing)

Contributions, issues, and feature requests are welcome! Feel free to check the [issues](https://github.com/zero-to-prod/omdb-api/issues) page if you want to contribute.

1. Fork the repository.
2. Create a new branch (`git checkout -b feature-branch`).
3. Commit changes (`git commit -m 'Add some feature'`).
4. Push to the branch (`git push origin feature-branch`).
5. Create a new Pull Request.

###  Health Score

29

—

LowBetter than 59% of packages

Maintenance41

Moderate activity, may be stable

Popularity19

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity37

Early-stage or recently created project

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

Total

5

Last Release

490d ago

PHP version history (2 changes)v1.0.3PHP >=8.1.0

v1.0.4PHP >=7.1.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/502649f05d36c87d494988bd99193a4d908d345335d99c080928a726277371f5?d=identicon)[zero-to-prod](/maintainers/zero-to-prod)

---

Top Contributors

[![zero-to-prod](https://avatars.githubusercontent.com/u/61474950?v=4)](https://github.com/zero-to-prod "zero-to-prod (3 commits)")

---

Tags

apiomdbphpzero-to-prodomdb apiOpen Movie Database API

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/zero-to-prod-omdb-api/health.svg)

```
[![Health](https://phpackages.com/badges/zero-to-prod-omdb-api/health.svg)](https://phpackages.com/packages/zero-to-prod-omdb-api)
```

###  Alternatives

[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[knplabs/github-api

GitHub API v3 client

2.2k15.8M187](/packages/knplabs-github-api)[facebook/php-business-sdk

PHP SDK for Facebook Business

90121.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

73813.7M114](/packages/meilisearch-meilisearch-php)[google/common-protos

Google API Common Protos for PHP

173103.7M50](/packages/google-common-protos)[hubspot/api-client

Hubspot API client

23414.2M16](/packages/hubspot-api-client)

PHPackages © 2026

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