README

Import movies from TMDB into Craft CMS entries. Search TMDB from the control panel, pick a result, and Movie Importer creates or updates an entry whose fields you map on the settings screen.

Features

Search TMDB in the Craft control panel and import a movie as an entry.
Paste and review up to 50 movies at once before adding the ready matches to Craft’s queue.
Map every field on your entry type — text values, images, genres and cast/crew credits — in a single settings table, stored per section/entry type.
Imports run through the queue, so large imports never block a web request.
Re-importing the same movie updates the existing entry in place (no duplicates).
The poster, backdrop and logo download into Craft Assets and relate to the entry.
A movie’s genres import as related entries in a section you choose — found-or-created and deduped, so the same genre is reused across movies and your hand-added genres are kept on re-import.
A movie’s cast and crew import as related People entries — map Entries fields on the movie entry type to the roles you want (cast, a specific job, or a whole department), with a shared headshot field and a configurable limit applied per role.
The TMDB API key is stored as an environment variable reference, never as a literal.

Requirements

Craft CMS 5.0.0+, PHP 8.2+, and a TMDB API key.

Installation

composer require tinch/craft-movie-importer
php craft plugin/install movie-importer

Setup

Add TMDB_API_KEY to your .env
Go to Settings → Plugins → Movie Importer
Set the API key to $TMDB_API_KEY
Choose the destination section and entry type
In the mapping table that appears, choose what each field receives — a TMDB value, an image, your movie’s genres, or a cast/crew credit — or leave it on “—”. Fields the plugin can’t map into show the reason instead of a choice.
If you mapped an Assets field to an image, pick its size (poster, backdrop, logo)
If you mapped any field to genres or a credit role, set the Genres and/or People section and entry type — where those entries get created — plus, for credits, how many people each field receives and, optionally, a headshot field and size
Open Movie Importer in the control panel’s main navigation. Its Search and Bulk import tabs let you import one movie or review a pasted list.

Imported entries are created disabled so an editor can review before publishing. Only users with permission to save entries in the destination section can search or import.

Bulk import

Paste up to 50 movies, one per nonblank line. A line can be a title, Title (Year), a bare TMDB movie ID, or a full themoviedb.org/movie/... URL. Prefix a numeric movie title with title:, as in title: 1917, so Movie Importer searches for the title instead of reading it as a TMDB ID.

Movie Importer resolves the list into a review table first. Title searches always require you to choose a match, even when TMDB returns only one result. Duplicates and already-imported movies are excluded from the ready count by default; select Re-import only when you intend to update that existing entry and overwrite its mapped fields. Every new movie entry is created disabled for an editor to review.

The pasted list and review choices live temporarily in this browser tab; they are not saved as a batch. Keep the page open while the ready rows are being submitted. After Movie Importer confirms that they are queued, you can leave the page and Craft’s queue will continue processing them.

Field mapping

Once you choose a section and entry type, the settings screen lists every field on it in a mapping table, grouped the same way as the entry's own edit screen. The entry's title is always the first row — it isn't something you map, since Movie Importer always writes the movie's title there — so the destination entry type should have a title field (or a title format); the table's title row warns you if it doesn't. Fields whose type Movie Importer can't map into (Matrix, Categories, and so on) are listed too, with the reason, rather than being left off.

Text (scalar) values map to your text fields. The mappable TMDB values are title, original title, tagline, overview, status, release date, runtime, original language, budget, revenue, homepage, TMDB rating, TMDB vote count, IMDb ID and TMDB ID.

Two things worth knowing about those values:

TMDB rating and vote count are a snapshot, written at import time and not kept in sync afterwards. They drift as people keep voting. Re-importing a movie refreshes them.
Budget and revenue are skipped when TMDB has no figure. TMDB reports an unknown budget or revenue as 0, which would read as “$0” rather than “unknown”, so those are treated as absent — leaving whatever you entered by hand untouched.

The poster, backdrop and logo images map to Assets fields; each image downloads once into that field’s own upload location and is re-fetched automatically if the asset is later deleted. Other relational field types (Categories, Matrix, …) aren’t part of the mapping, aside from the Entries fields covered next.

One more thing worth knowing about the logo:

The logo is picked for you, and some films have none. TMDB doesn’t designate a single primary logo — only a list of candidates in different languages — so Movie Importer chooses one in your primary site’s language if available, otherwise an English one, otherwise the first logo TMDB lists, which is TMDB’s own ranking. There’s no setting to choose a language or pick a specific logo. Films with no logo on TMDB at all are common for obscure or low-popularity titles; when that happens the field is left empty and nothing is reported.

Genres and cast/crew both map through Entries fields on the movie entry type, using the same row in the mapping table: each Entries field is set to receive one thing — your movie’s genres, the whole cast, a specific crew job, or a whole crew department — and more than one field can be set to receive genres, if you want. A crew role is a specific job (Director, Screenplay, Writer, Story, Novel, Producer, Executive Producer, Director of Photography, Editor, Original Music Composer, Production Designer, Costume Designer or Casting), or a whole department (Directing, Writing, Production, Camera, Editing, Sound, Art, Costume & Make-Up, Visual Effects, Lighting or Crew). Both job and department are offered because neither alone is reliable: on a sample of six films, mapping the job Writer matched nobody on Fight Club, The Godfather or Parasite — their writing credits used job titles like Novel, Screenplay and Story instead — while mapping the whole Directing department on Fight Club pulled in five people, including two assistant directors and a script supervisor, alongside the director. Use whichever axis actually matches the credit you're after.

Credited people are found-or-created in a People section and entry type you choose, and related through the field mapped to their role. A person is identified by their TMDB person id, never by name, so an existing entry with the same title is never reused — TMDB has more than one person named “Chris Evans”, for example. If an entry with that name already exists and isn't linked to that TMDB person, Movie Importer creates a second entry rather than guessing, and logs a warning naming the collision so you can find and merge it by hand. New person entries are created enabled.

A People per role setting caps how many people each mapped field relates — a film's full crew list can run into the hundreds — applied per field, after duplicates are removed, with a default of 10. Re-importing a film adds the people TMDB credits without removing anyone you related to a mapped field by hand.

A person's headshot can map to an Assets field on the person entry type, at a configurable size, downloading once and re-fetching automatically like the other images. Movie Importer owns that field: it's replaced on every import that credits the person, including a headshot you set by hand. A person with no headshot on TMDB is skipped, with no warning.

License

Movie Importer is commercial software. A license costs $39 (one-time) with an optional $15/year renewal for continued updates and support after the first year; the plugin keeps working without renewing. You can trial it for free on any non-public (local/staging) domain — a license is only required once the site goes live. See LICENSE.md.

Support

Issues: https://github.com/rogertinch/craft-movie-importer/issues
Email: ret@tinch.co

Attribution

This product uses the TMDB API but is not endorsed or certified by TMDB.

tinch / craft-movie-importer

Package info

Security

Statistics