Calendar

This describes the working of Calendar class with description of the used method comingSoon() and what data it returns

Calendar class get information of upcoming releases like IMDb displays on their calendar page: https://www.imdb.com/calendar/ It returns a array of titles found within the given date span with a (possible?) limit of 100 titles.

comingSoon Method Documentation

This method fetches information about upcoming movies, TV series or TV Episodes based on specified parameters such as type, region, and date range. It returns a structured array containing details like the title, release date, genres, cast, and image URLs.

---

Method Signature

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

Parameters

The method accepts a single argument, an associative array $params. This array allows users to customize the query.

Parameter	Type	Default	Description
type	string	"MOVIE"	Defines the type of content. Possible values: "MOVIE", "TV", "TV_EPISODE".
region	string	"US"	The region for which to retrieve data (e.g., "US", "UK").
disablePopularityFilter	string	"true"	This defines if disablePopularityFilter is set or not, set to false shows all releases, true only returns popular releases so less results within the given date span
startDateOverride	int	0	Days from today for the start of the date range (e.g., 0 for today).
endDateOverride	int	90	Days from today for the end of the date range (e.g., 90 for 90 days out).

Example Usage

// Fetch movies releasing in the US within the next 90 days (default behavior)
$result = $this->comingSoon();

// Fetch TV series releasing in the UK within the next 30 days
$result = $this->comingSoon([
    'type' => 'TV',
    'region' => 'UK',
    'startDateOverride' => 0,
    'endDateOverride' => 30
]);

---

Return Value

The method returns an array of upcoming Movies, TV series or TV Episodes. Each entry in the array is an associative array with the following structure:

Key	Type	Description
id	string	The IMDb ID of the content.
title	string	The title of the content.
releaseDate	array	The release date, containing day, month, and year.
genres	string[]	An array of genres associated with the content.
cast	string[]	An array of cast member names.
imageUrl	string[]	An array of URL to the primary image or poster of the content.

Example Return

[
    [
        "id" => "tt1234567",
        "title" => "Upcoming Movie",
        "releaseDate" => [
            "day" => 12,
            "month" => 6,
            "year" => 2024
        ],
        "genres" => ["Action", "Adventure"],
        "cast" => ["Actor One", "Actor Two"],
        "imageUrl" => "https://example.com/image.jpg"
    ],
    // More entries...
]

---

Error Handling

If no valid results are found (e.g., if content lacks an IMDb ID or title), those entries are skipped.

---

Notes

1. Default Values: If no $params are provided, the method defaults to returning movies (type => "MOVIE") in the US (region => "US") releasing in the next 90 days.
2. GraphQL Query: The method uses a GraphQL query to fetch the required data from an external service.
3. Date Calculation: The method computes the startDate and futureDate based on the current date, modified by the startDateOverride and endDateOverride parameters.