https://github.com/zero-to-prod/omdb
A PHP wrapper for the OMDb API with full object support
https://github.com/zero-to-prod/omdb
data-model omdb omdb-api php
Last synced: 3 months ago
JSON representation
A PHP wrapper for the OMDb API with full object support
- Host: GitHub
- URL: https://github.com/zero-to-prod/omdb
- Owner: zero-to-prod
- License: mit
- Created: 2024-12-30T17:30:07.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-20T19:29:55.000Z (12 months ago)
- Last Synced: 2025-03-25T17:07:25.816Z (11 months ago)
- Topics: data-model, omdb, omdb-api, php
- Language: PHP
- Homepage: https://zero-to-prod.github.io/omdb/
- Size: 157 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Zerotoprod\Omdb
[](https://github.com/zero-to-prod/omdb)
[](https://github.com/zero-to-prod/omdb/actions)
[](https://github.com/zero-to-prod/omdb/actions)
[](https://packagist.org/packages/zero-to-prod/omdb/stats)
[](https://packagist.org/packages/zero-to-prod/omdb)
[](https://github.com/zero-to-prod/omdb/blob/main/LICENSE.md)
[](https://wakatime.com/badge/github/zero-to-prod/omdb)
[](https://hitsofcode.com/github/zero-to-prod/omdb/view?branch=main)
## Contents
- [Introduction](#introduction)
- [TLDR](#tldr)
- [Requirements](#requirements)
- [Getting an OMDb API Key](#getting-an-omdb-api-key)
- [Installation](#installation)
- [Documentation Publishing](#documentation-publishing)
- [Automatic Documentation Publishing](#automatic-documentation-publishing)
- [Usage](#usage)
- [poster()](#poster)
- [byIdOrTitle()](#byidortitle)
- [search()](#search)
- [Factories](#factories)
- [Mocking](#mocking)
- [Local Development](./LOCAL_DEVELOPMENT.md)
- [Contributing](#contributing)
## Introduction
`Zerotoprod\OmdbApi` is a PHP cURL wrapper for the [OMDb API](https://www.omdbapi.com/) with full object support.
It allows you to search for movies, series, and other media, retrieve detailed information using IMDb IDs or titles, and fetch poster images.
It wraps the [OmdbApi](https://github.com/zero-to-prod/omdb-api) and returns fully hydrated models using the
[OmdbModels](https://github.com/zero-to-prod/omdb-models) package.
## TLDR
```php
use Zerotoprod\Omdb\Omdb;
$Omdb = Omdb::from('apiKey');
// Get the poster art of a title by its ImdbID
$Omdb->poster('tt0499549'); // https://img.omdbapi.com/?apikey=8f8423aa&i=tt0499549
// Find a title by ImdbID (Internet Movie DataBase ID) or title
$Omdb->byIdOrTitle('Avatar')->Title; // 2009
// Find multiple titles
$Omdb->search('Avatar')->Search['tt0499549']->Year; // 2009
```
## 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
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
Install `Zerotoprod\Omdb` via [Composer](https://getcomposer.org/):
```shell
composer require zero-to-prod/omdb
```
This will add the package to your project's dependencies and create an autoloader entry for it.
## Documentation Publishing
You can publish this README to your local documentation directory.
This can be useful for providing documentation for AI agents.
This can be done using the included script:
```bash
# Publish to default location (./docs/zero-to-prod/omdb)
vendor/bin/zero-to-prod-omdb
# Publish to custom directory
vendor/bin/zero-to-prod-omdb /path/to/your/docs
```
### Automatic Documentation Publishing
You can automatically publish documentation by adding the following to your `composer.json`:
```json
{
"scripts": {
"post-install-cmd": [
"zero-to-prod-omdb"
],
"post-update-cmd": [
"zero-to-prod-omdb"
]
}
}
```
## Usage
Initialization:
```php
use Zerotoprod\Omdb\Omdb;
$Omdb = Omdb::from('apiKey');
```
You can also customize the base URL and the poster URL if you need to (for example, to proxy through another service):
```php
use Zerotoprod\Omdb\Omdb;
$Omdb = Omdb::from(
apikey: 'apiKey',
base_url: 'https://www.omdbapi.com/',
img_url: 'https://img.omdbapi.com/'
);
```
### poster()
Get the poster art of a title by its ImdbID
```php
$Omdb->poster('tt0499549'); // https://img.omdbapi.com/?apikey=8f8423aa&i=tt0499549
```
### byIdOrTitle()
Find a title by ImdbID (Internet Movie DataBase ID) or title.
Returns a [Title DataModel](https://github.com/zero-to-prod/omdb-models/blob/main/src/Title.php).
```php
$Omdb->byIdOrTitle('Avatar')->Title; // 2009
```
### search()
Find multiple titles. Note the `imdbID` value is used as the key for each movie.
Returns a [SearchResults DataModel](https://github.com/zero-to-prod/omdb-models/blob/main/src/SearchResults.php).
```php
$Omdb->search('Avatar')->Search['tt0499549']->Year; // 2009
```
### Factories
You can use the [provided factories](https://github.com/zero-to-prod/omdb-models#factories) without going through the api like this:
```php
\Zerotoprod\OmdbModels\Factories\TitleFactory::factory()->setTitle('Avatar')->make();
```
### Mocking
You can mock the api by implementing
the [Zerotoprod\OmdbApi\OmdbApiInterface](https://github.com/zero-to-prod/omdb-api/blob/main/src/OmdbApiInterface.php):
```php
use Zerotoprod\OmdbApi\OmdbApiInterface;
use Zerotoprod\Omdb\Omdb;
class OmdbApiFake implements OmdbApiInterface
{
public function search()
}
$Omdb = new Omdb(new OmdbApiFake());
$Omdb->search('Avatar');
```
## Contributing
Contributions, issues, and feature requests are welcome!
Feel free to check the [issues](https://github.com/zero-to-prod/omdb/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.