detain / phlix-plugin-omdb

v0.3.0 2026-10-30 20:24 UTC

Requires

• php: >=8.3
• detain/phlix-shared: ^0.21.0
• psr/container: ^1.1 || ^2.0
• psr/log: ^1.0 || ^2.0 || ^3.0

Requires (Dev)

• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^10.0
• squizlabs/php_codesniffer: ^4.0
• workerman/http-client: ^1.0
• workerman/workerman: ^4.0

MIT

• metadata
• imdb
• movies
• ratings
• tv
• omdb
• metadata-provider
• phlix
• phlix-plugin
• rotten-tomatoes

Published on Packagist.org on 2026-11-02 14:35 UTC

README

OMDb metadata provider for Phlix — IMDb and Rotten Tomatoes ratings for movies and TV.

Queries the OMDb API to enrich Phlix media items with IMDb ID and IMDb / Rotten Tomatoes ratings. Ratings are returned under the valid metadata_ratings.source ENUM values (imdb, rt); OMDb's Metacritic rating is read but deliberately dropped — the ENUM has no member for it. The host resolver owns writing ratings and Phlix's rating aggregation.

Features

• IMDb ID resolution — search by title (with an optional release-year hint) to resolve the canonical IMDb ID
• Multi-source ratings — captures IMDb and Rotten Tomatoes scores
• Async HTTP — HTTPS-only Workerman client, with a bounded blocking-cURL fallback for event loops (Swoole) where async TLS reads cannot complete
• Rate limiting — fixed minimum spacing between calls (0.25s), plus an automatic pause until the next UTC midnight once OMDb reports that your API key has used up its daily request allowance; the interval is not a setting
• Response caching — configurable in-memory cache TTL to reduce API calls (0 disables the cache; capped at 30 days)
• TLS verification toggle — advanced escape hatch that disables certificate checking. OMDb authenticates with your key in the URL query string, so unverified TLS lets an intercepting hop harvest the API key. Keep it on; use off only when debugging behind a proxy you control
• Pure read — getDetails() fetches and shapes data only; onEnable() does no network or DB I/O and never throws on a missing key

Install

The plugin is unsigned by design — install via the Phlix admin UI:

1. Log in to your Phlix server as an admin user (users.is_admin = 1).

2. Browse to /admin/plugins.

3. Paste this URL into the Install from URL form and submit:

   https://raw.githubusercontent.com/detain/phlix-plugin-omdb/master/plugin.json
   

4. The server downloads the manifest, validates it, runs composer install --no-dev, and stores a row in the plugins table. The plugin lands disabled by default.

5. Enter your OMDb API key in the plugin settings (get one at OMDb API).

6. Flip the toggle in the table to enable it.

Settings

plugin.json is the canonical source for these settings; each label and description below is copied from it verbatim, so edit plugin.json first and mirror the change here.

Setting	Label	Type	Required	Secret	Tier	Default	Description
enabled	Enable OMDb lookups	boolean	No	No	standard	false	Turns OMDb rating lookups on or off. Optional; default off.
api_key	OMDb API Key	string	Yes	Yes	standard	null	Your OMDb API key. The free tier allows 1,000 requests/day.
use_ssl_verification	Verify TLS certificate	boolean	No	No	advanced	true	Verify the TLS certificate presented by OMDb. Keep this on. Turning it off lets any intercepting hop read and tamper with the traffic — including your API key, which the plugin sends to OMDb in the URL query string and which could be stolen. Use off only when debugging behind a proxy you control.
cache_ttl_seconds	Cache TTL (seconds)	integer	No	No	advanced	86400	How long to cache OMDb responses; 0 disables the cache. Values above 2,592,000 (30 days) are lowered to 2,592,000, and negative values disable the cache. Optional; default 86400 (24 hours).

Where to get your OMDb API key

The api_key setting is required. Request a free key at https://www.omdbapi.com/apikey.aspx — the free tier allows 1,000 requests/day.

What it does

When enabled, the plugin registers as a MetadataSourceInterface provider. When the Phlix metadata manager requests details for a media item:

1. The plugin receives the search query (title + optional year hint)
2. It queries OMDb's search endpoint to find matching entries — the year is sent as y=, but OMDb only documents it as a disambiguator for the single-title (t=) lookup, so search results are not guaranteed to be year-filtered; callers that need a strict filter match the returned year
3. It fetches full details including ratings for the selected IMDb ID
4. Ratings are returned as a ratings list using the metadata_ratings.source ENUM values (imdb, rt) for the host resolver to persist and aggregate

Supported media types

• movie
• series

Running tests locally

composer install
vendor/bin/phpunit
vendor/bin/phpstan analyse src --level=9
vendor/bin/phpcs src --standard=PSR12
php scripts/security-audit-check.php

The composer-audit job in .github/workflows/test.yml runs php scripts/security-audit-check.php, which audits the whole composer.lock (require and require-dev) and fails the job on any security advisory; see the script header for the full blocking policy.

License

MIT — see LICENSE.