README

OMDb metadata provider for Phlix — IMDb/RT ratings aggregation 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 Metascore field 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 + year to resolve the canonical IMDb ID
Multi-source ratings — captures IMDb and Rotten Tomatoes scores (Metascore is dropped — no valid metadata_ratings.source ENUM member)
Non-blocking HTTP — async HTTPS-only client compatible with Workerman's event loop
Rate limiting — fixed minimum spacing between calls (0.25s), plus an automatic cooldown to the next UTC midnight when OMDb reports a daily-limit envelope; the interval is not a setting
Response caching — configurable in-memory cache TTL to reduce API calls
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:

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

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

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

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.
Flip the toggle in the table to enable it.
Enter your OMDb API key in the plugin settings (get one at OMDb API).

Settings

Setting	Type	Required	Secret	Tier	Default	Description
`enabled`	boolean	No	No	`standard`	`false`	Master on/off for OMDb rating enrichment. Optional; default off.
`api_key`	string	Yes	Yes	`standard`	`null`	Your OMDb API key. The free tier allows 1,000 requests/day.
`use_ssl_verification`	boolean	No	No	`advanced`	`true`	Verify OMDb's TLS certificate. Keep on — off exposes the query-string API key to interception/theft; debugging behind a trusted proxy only.
`cache_ttl_seconds`	integer	No	No	`advanced`	`86400`	How long to cache OMDb responses; `0` disables 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:

The plugin receives the search query (title + optional year)
It queries OMDb's search endpoint to find matching entries
It fetches full details including ratings for the selected IMDb ID
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 blocks on any advisory.

License

MIT — see LICENSE.

detain / phlix-plugin-omdb

Package info

Security

Statistics