$params the request parameters to send to the API * @return mixed a JSON object containing the API's response * @throws WikipediaException if the request fails */ private function api_fetch(array $params): mixed { $ch = curl_init(); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_URL, self::API_URL . http_build_query($params)); curl_setopt($ch, CURLOPT_USERAGENT, self::USER_AGENT); $output = curl_exec($ch); curl_close($ch); if (is_bool($output) || curl_error($ch)) throw new WikipediaException(curl_error($ch)); try { return json_decode($output, associative: true, flags: JSON_THROW_ON_ERROR); } catch (JsonException $exception) { throw new WikipediaException($exception->getMessage(), previous: $exception); } } /** * Sends a query request to Wikipedia's API with continuation and returns its response as a JSON object. * * @param array $params the query request parameters to send to the API * @param string|null $continue_name the name of the continue parameter to follow, or `null` if no continuation * should be done * @return mixed[] a JSON array containing the API's responses merged into one array * @throws WikipediaException if the query fails */ private function api_query_continued(array $params, ?string $continue_name = null): array { $query_params = array_merge(["action" => "query", "format" => "json"], $params); $response = []; $continue = null; $continue_value = null; do { $continue_params = $continue === null ? $query_params : array_merge($query_params, ["continue" => $continue, $continue_name => $continue_value]); $new_response = $this->api_fetch($continue_params); $response = Util::array_merge_recursive_distinct($response, $new_response); if (isset($response["batchcomplete"])) { $continue = null; $continue_value = null; } else if ($continue_name !== null) { $continue = $response["continue"]["continue"]; $continue_value = $response["continue"][$continue_name]; } } while ($continue !== null); return $response; } /** * Sends a query request to the Wikipedia API in batches of {@see Wikipedia::ARTICLES_PER_QUERY} titles at a time. * * @param array $params the parameters to include in each query * @param string[] $titles the titles of the pages to query * @param string|null $continue_name the name of the continue parameter to follow for this request * @return QueryOutput the API's responses merged into a single `QueryOutput` * @throws WikipediaException if the query fails * @noinspection PhpSameParameterValueInspection `$continue_name` may take other values in the future */ private function api_query_batched(array $params, array $titles, ?string $continue_name): QueryOutput { $articles = []; $redirects = array_combine($titles, $titles); $missing = []; $title_chunks = array_chunk($titles, self::ARTICLES_PER_QUERY); foreach ($title_chunks as $title_chunk) { $chunk_params = array_merge($params, ["titles" => implode("|", $title_chunk), "redirects" => true]); $response = $this->api_query_continued($chunk_params, $continue_name)["query"]; foreach ($response["pages"] as $article_id => $article) { if ($article_id < 0) $missing[] = strval($article["title"]); else $articles[strval($article["title"])] = $article; } $response_normalized = array_column($response["normalized"] ?? [], "to", "from"); foreach ($response_normalized as $from => $to) $redirects[strval($from)] = strval($to); $response_redirects = array_column($response["redirects"] ?? [], "to", "from"); foreach ($response_redirects as $from => $to) { $pre_normalized = array_search($from, $response_normalized); $redirects[strval($pre_normalized === false ? $from : $pre_normalized)] = strval($to); } } return new QueryOutput($articles, $redirects, $missing); } /** * Returns the current {@see ArticleType} of the article. * * @param mixed $article the article object as returned by the Wikipedia API * @return ArticleType the current `ArticleType` of article */ private function article_type(mixed $article): ArticleType { $category_titles = array_column($article["categories"], "title"); $status = $this->person_status($article); if ($status !== null) return ArticleType::Person; else if (in_array("Category:All set index articles", $category_titles) || in_array("Category:All disambiguation pages", $category_titles)) return ArticleType::Disambiguation; else return ArticleType::Other; } /** * Returns the current {@see PersonStatus}, or `null` if the title does not refer to an article about a person on * Wikipedia. * * @param mixed $article the article as returned by the Wikipedia API * @return PersonStatus|null the current `PersonStatus`, or `null` if the title does not refer to an article about a * person on Wikipedia */ private function person_status(mixed $article): ?PersonStatus { if (array_key_exists("missing", $article) || array_key_exists("invalid", $article)) return null; $category_titles = array_column($article["categories"], "title"); $dead_regex = "/^Category:([0-9]{1,4}s? (BC |AD )?deaths|Year of death (missing|unknown))$/"; if (!empty(array_filter($category_titles, fn($it) => preg_match($dead_regex, $it)))) return PersonStatus::Dead; elseif (in_array("Category:Possibly living people", $category_titles)) return PersonStatus::PossiblyAlive; elseif (in_array("Category:Missing people", $category_titles)) return PersonStatus::Missing; elseif (in_array("Category:Living people", $category_titles)) return PersonStatus::Alive; else return null; } /** * Checks for all {@see $names} what their current {@see ArticleType} and {@see PersonStatus} is according to * Wikipedia. * * @param string[] $names the names of the people to retrieve the information of * @return QueryOutput a `QueryOutput` with its * {@see QueryOutput::$results} mapping each normalized title to its `ArticleType` and, if the type is `Person`, the * `PersonStatus` * @throws WikipediaException if the query fails */ public function query_person_info(array $names): QueryOutput { $output = $this->api_query_batched( params: ["prop" => "categories", "cllimit" => strval(self::CATS_PER_QUERY)], titles: $names, continue_name: "clcontinue" ); $articles = array_combine( array_column($output->results, "title"), array_map( fn($it) => [ "type" => $this->article_type($it), "status" => $this->person_status($it), ], $output->results ) ); return new QueryOutput($articles, $output->redirects, $output->missing); } }