NameSerarch

NameSearch Class Documentation

The NameSearch class extends the Base class and provides functionality to perform advanced name searches using various parameters such as name, birth date, gender, etc. The class allows users to query and retrieve name records, along with additional details such as bio, image, and professions.

Public Method

search(array $params = []): array

Performs an advanced search based on the input parameters and returns an array of name records.

Parameters

• params (array): The input parameters for the search. The array supports the following keys:

  Key	Type	Description
  name	string	The name to search for. Can be an empty string to search without a name filter.
  birthMonthDay	string	Birthdate in MM-DD format, with 2 digits for the month and day (e.g., 01-15).
  birthDateRangeStart	string	Birthdate search start
  birthDateRangeEnd	string	Birthdate search end
  deathDateRangeStart	string	Deathdate search start
  deathDateRangeEnd	string	Deathdate search end
  birthPlace	string	birthPlace (like Amesterdam)
  gender	string	Gender filter. Can be one of MALE, FEMALE, NON_BINARY, OTHER.
  adult	string	Explicit content filter. Can be EXCLUDE_ADULT or INCLUDE_ADULT.
  limit	int	The number of records to return. Default is 50.
  sortBy	string	Sorting criteria. Can be POPULARITY, NAME, BIRTH_DATE, or DEATH_DATE.
  sortOrder	string	Sorting order. Can be ASC for ascending or DESC for descending.

Example

$params = [
    'name' => 'John',
    'birthMonthDay' => '01-15',
    'gender' => 'MALE',
    'adult' => 'EXCLUDE_ADULT',
    'limit' => 10,
    'sortBy' => 'NAME',
    'sortOrder' => 'ASC'
];

$searchResults = $nameSearch->search($params);

Return Value

• Returns an array of search results, where each record includes the following details:

  Key	Type	Description
  index	int	The index of the result in the list (starts from 1).
  id	string	The IMDb ID of the person (starts with nm).
  url	string	Full IMDb URL of the person.
  name	string	The name of the person.
  imageUrl	string	URL of the person's image (if available).
  professions	array	Primary profession(s) of the person (e.g., Actor, Director, Writer).
  bio	string	Biography of the person.

Example Return

[
  [
    'index' => 1,
    'id' => 'nm0000123',
    'url' => 'https://www.imdb.com/name/nm0000123',
    'name' => 'John Doe',
    'imageUrl' => 'https://image.tmdb.org/t/p/original/example.jpg',
    'professions' => ['Actor', 'Producer'],
    'bio' => 'John Doe is a well-known actor and producer...',
  ],
  // More records...
]

Exception Handling

• Throws Exception: The method will throw an exception if there is an issue with the GraphQL query or data processing.

Internal Workflow

1. Default Parameter Values: The method sets default values for the parameters (e.g., limit is set to 50, and sorting is by POPULARITY in ascending order).
2. Query Generation: A GraphQL query is dynamically built based on the provided parameters.
3. Result Formatting: The returned data is formatted into an array of results, each containing the name, IMDb ID, URL, image, profession, and bio.

Example Usage

$nameSearch = new NameSearch();

// Search for all female actors born on January 15, excluding adult content
$params = [
    'name' => '',
    'birthMonthDay' => '01-15',
    'gender' => 'FEMALE',
    'adult' => 'EXCLUDE_ADULT',
    'limit' => 5,
    'sortBy' => 'POPULARITY',
    'sortOrder' => 'DESC'
];

$results = $nameSearch->search($params);

foreach ($results as $result) {
    echo "Name: {$result['name']}\n";
    echo "URL: {$result['url']}\n";
    echo "Bio: {$result['bio']}\n";
}

Notes

• The limit parameter controls how many results are returned. Adjust this value for performance when large datasets are queried.
• The sorting options (sortBy, sortOrder) allow you to customize the order of the results based on popularity, name, or birth/death dates.