Trailers - hooshid/imdb-scraper GitHub Wiki

Trailers Class

The Trailers class provides access to movie and TV trailers from IMDb, including both recent and trending videos.

recentVideos()

Method Documentation

Retrieves the most recently added trailers on IMDb. Returns detailed information about each trailer including associated title metadata.

Method Signature

public function recentVideos(int $limit = 100): array

Parameters

Parameter Type Default Required Description
limit int 100 NO Maximum number of trailers to retrieve

Example Usage

$trailers = new \Hooshid\ImdbScraper\Trailers();
$recent = $trailers->recentVideos(50);

Return Value

Key Type Description
id string Video ID
playback_url string Full URL to watch the trailer
created_date string|null Creation date (YYYY-MM-DD HH:MM:SS)
runtime_formatted string|null Human-readable runtime (MM:SS)
runtime_seconds int|null Runtime in seconds
title string|null Trailer title
description string|null Trailer description
content_type string|null Type of video content
thumbnail array|null Thumbnail image data
thumbnail.url string Image URL
thumbnail.width int Image width
thumbnail.height int Image height
primary_title array Associated title info
primary_title.id string IMDb title ID
primary_title.title string|null Title name
primary_title.release_date string|null Release date (YYYY-MM-DD)
primary_title.release_date_displayable string|null Formatted release date
primary_title.image array|null Title image data
primary_title.image.url string Image URL
primary_title.image.width int Image width
primary_title.image.height int Image height

Example Return

[
    {
        "id": "vi1776601113",
        "playback_url": "https://www.imdb.com/video/vi1776601113/",
        "created_date": "2025-06-27 20:35:55",
        "runtime_formatted": "2:10",
        "runtime_seconds": 130,
        "title": "Official Trailer 2",
        "description": "Meeting an old friend...",
        "content_type": "Trailer",
        "thumbnail": {
            "url": "https://m.media-amazon.com/images/M/MV5BMjIyODI0NDktMzA5Mi00MzJlLTgyOTQtYmM2MDY0NTEyZjU1XkEyXkFqcGdeQWRpZWdtb25n._V1_.jpg",
            "width": 1920,
            "height": 1080
        },
        "primary_title": {
            "id": "tt28659066",
            "title": "Avani",
            "release_date": "2025-09-01",
            "release_date_displayable": "September 1, 2025",
            "image": {
                "url": "https://m.media-amazon.com/images/M/MV5BMzgxMzk4Y2YtNWU5Yy00MDBhLWJkNDYtMmIwNjNhMzYwYzYyXkEyXkFqcGc@._V1_.jpg",
                "width": 2400,
                "height": 3600
            }
        }
    }
]

Error Handling

  • Returns empty array if:
    • No recent trailers found
    • Invalid API response structure
  • Throws Exception on API request failure

Notes

  • Default limit is 100 trailers
  • Only returns trailer content type
  • Playback URLs link directly to IMDb's video player

trendingVideos()

Method Documentation

Retrieves currently trending trailers on IMDb based on popularity. Returns detailed information about each trailer and associated title.

Method Signature

public function trendingVideos(int $limit = 250): array

Parameters

Parameter Type Default Required Description
limit int 250 NO Maximum number of trailers to retrieve

Example Usage

$trailers = new \Hooshid\ImdbScraper\Trailers();
$trending = $trailers->trendingVideos(25);

Return Value

Key Type Description
id string Video ID
playback_url string Full URL to watch the trailer
created_date string|null Creation date (YYYY-MM-DD HH:MM:SS)
runtime_formatted string|null Human-readable runtime (MM:SS)
runtime_seconds int|null Runtime in seconds
title string|null Trailer title
description string|null Trailer description
content_type string|null Type of video content
thumbnail array|null Thumbnail image data
thumbnail.url string Image URL
thumbnail.width int Image width
thumbnail.height int Image height
primary_title array Associated title info
primary_title.id string IMDb title ID
primary_title.title string|null Title name
primary_title.release_date string|null Release date (YYYY-MM-DD)
primary_title.release_date_displayable string|null Formatted release date
primary_title.image array|null Title image data
primary_title.image.url string Image URL
primary_title.image.width int Image width
primary_title.image.height int Image height

Example Return

[
    {
        "id": "vi3353462809",
        "playback_url": "https://www.imdb.com/video/vi3353462809/",
        "created_date": "2025-06-25 17:00:45",
        "runtime_formatted": "2:25",
        "runtime_seconds": 145,
        "title": "Final Trailer",
        "description": "Set against the vibrant backdrop...",
        "content_type": "Trailer",
        "thumbnail": {
            "url": "https://m.media-amazon.com/images/M/MV5BMDRjNGVlNDgtZGE0ZS00MWMxLWE0OWItZjY3NjI5MjcyZDNjXkEyXkFqcGdeQXZ3ZXNsZXk@._V1_.jpg",
            "width": 2733,
            "height": 1537
        },
        "primary_title": {
            "id": "tt10676052",
            "title": "The Fantastic Four: First Steps",
            "release_date": "2025-07-25",
            "release_date_displayable": "July 25, 2025",
            "image": {
                "url": "https://m.media-amazon.com/images/M/MV5BOGM5MzA3MDAtYmEwMi00ZDNiLTg4MDgtMTZjOTc0ZGMyNTIwXkEyXkFqcGc@._V1_.jpg",
                "width": 1086,
                "height": 1609
            }
        }
    }
]

Error Handling

  • Returns empty array if:
    • No trending trailers found
    • Invalid API response structure
  • Throws Exception on API request failure

Notes

  • Default limit is 250 trailers
  • Trending status updates frequently based on viewer activity
  • Only returns the latest trailer for each trending title
  • Release dates may be approximate for upcoming titles