Calendar Class

The Calendar class provides access to upcoming movie and TV release information from IMDb. https://www.imdb.com/calendar/

comingSoon()

Method Documentation

Retrieves a list of upcoming movie and TV releases with details including release dates, genres, and cast members. Results can be filtered by content type and region.

Method Signature

public function comingSoon(array $params = []): array

Parameters

Parameter	Type	Default	Required	Description
type	string	MOVIE	NO	Content type (MOVIE, TV, TV_EPISODE)
region	string	US	NO	Region code (e.g. US, UK)
disablePopularityFilter	string	true	NO	Whether to disable popularity filter
startDateOverride	int	0	NO	Days from today for start date
endDateOverride	int	90	NO	Days from today for end date

Valid type Values

• MOVIE: Feature films
• TV: Television shows
• TV_EPISODE: Individual TV episodes

Example Usage

$calendar = new \Hooshid\ImdbScraper\Calendar();

// Get upcoming movies
$movies = $calendar->comingSoon();

// Get upcoming TV shows in UK
$tvShows = $calendar->comingSoon([
    'type' => 'TV',
    'region' => 'UK'
]);

// Get releases for next 30 days
$nextMonth = $calendar->comingSoon([
    'endDateOverride' => 30
]);

Return Value

Key	Type	Description
id	string	IMDb title ID
title	string	Title name
release_date	string	Release date (YYYY-MM-DD)
genres	string[]	Array of genre names
cast	string[]	Array of principal cast members
image	array|null	Primary image data
image.url	string	Image URL
image.width	int	Image width in pixels
image.height	int	Image height in pixels

Example Return

[
    {
        "id": "tt16311594",
        "title": "F1: The Movie",
        "release_date": "2025-06-27",
        "genres": [
            "Action",
            "Drama", 
            "Sport"
        ],
        "cast": [
            "Brad Pitt",
            "Damson Idris"
        ],
        "image": {
            "url": "https://m.media-amazon.com/images/M/MV5BOWRiOThkM2YtYzI4NS00OWViLTk0ODMtMjNlNDYyZWQ3MzNjXkEyXkFqcGc@._V1_.jpg",
            "width": 1638,
            "height": 2048
        }
    }
]

Error Handling

• Returns empty array if:
  • Invalid type parameter provided
  • No upcoming releases found
  • API returns invalid data structure
• Throws Exception on API request failure

Notes

• Default date range is today to 90 days in future
• Region codes follow ISO 3166-1 alpha-2 format
• Cast list limited to principal actors
• Image URLs may expire after some time
• TV episodes may not include full series metadata