223 lines
8.7 KiB
PHP
223 lines
8.7 KiB
PHP
<?php
|
|
|
|
namespace com\fwdekker\deathnotifier\wikipedia;
|
|
|
|
use com\fwdekker\deathnotifier\Util;
|
|
use JsonException;
|
|
|
|
|
|
/**
|
|
* Helper class for interacting with Wikipedia's API.
|
|
*/
|
|
class Wikipedia
|
|
{
|
|
/**
|
|
* The URL of Wikipedia's API endpoint.
|
|
*/
|
|
private const API_URL = "https://en.wikipedia.org/w/api.php?";
|
|
/**
|
|
* The user agent used to represent the death notifier to Wikipedia.
|
|
*/
|
|
private const USER_AGENT =
|
|
"death-notifier/%%VERSION_NUMBER%% " .
|
|
"(https://git.fwdekker.com/tools/death-notifier; florine@fwdekker.com)";
|
|
/**
|
|
* Number of articles to query per query.
|
|
*/
|
|
private const ARTICLES_PER_QUERY = 50;
|
|
/**
|
|
* Number of categories to return per article per query.
|
|
*
|
|
* Since the record for a single article is 252 categories, setting this to the maximum of 500 is more than
|
|
* sufficient.
|
|
*/
|
|
private const CATS_PER_QUERY = 500;
|
|
|
|
|
|
/**
|
|
* Sends a request to Wikipedia's API and returns its response as a JSON object.
|
|
*
|
|
* @param array<string, mixed> $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<string, mixed> $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<string, mixed> $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<mixed> 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<array{"type": ArticleType, "status": PersonStatus|null}> 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);
|
|
}
|
|
}
|