README

此项目使PHP开发者能够在PHP代码中使用

• MediaWiki REST API
• 和Wikimedia REST API。

安装

您可以通过composer安装此包

composer require ekut/mediawiki-sdk-php

• 注意：此包仅支持php:^8.0。

用法

通常，我们通过以下方式使用SDK

  $wiki = new \MediawikiSdkPhp\MediaWiki();
  $params = ['foo'=>'bar'];
  /** @var \Spatie\DataTransferObject\DataTransferObject $res */
  $res = $wiki->{ResourceName()}->{ActionName($params)}
  /** @var array $data */
  $data = $res->toArray();

默认语言是英语。如果我们想使用其他语言，我们可以在MediaWiki构造函数中设置它

  $wiki = new \MediawikiSdkPhp\MediaWiki('ru');

真实示例：见下文。错误处理：见下文。

配置 (.env)

该包使用vlucas/phpdotenv来设置环境变量。您需要做的就是在一个根项目文件夹中填写.env文件，包含两个变量/值

MEDIAWIKI_HOST="https://www.wikipedia.org/"
COMMONS_HOST="https://commons.wikimedia.org/"

可用资源和操作

MediaWiki REST API

• 文件
  • 获取
• 页面
  • 创建 - @ToDo
  • 更新 - @ToDo
  • 获取
  • 获取离线版本
  • 获取源代码
  • 获取HTML
  • 获取语言
  • 获取文件
  • 获取历史记录
  • 获取历史记录数量
• 修订
  • 获取
  • 比较
• 搜索
  • 页面
  • 自动完成页面标题

Wikimedia REST API

• 页面内容
  • 获取页面摘要
  • 获取页面标题
• 移动 - @ToDo
• 源 - @ToDo
• 转换 - @ToDo
• 数学 - @ToDo
• 引用 - @ToDo
• 阅读列表 - @ToDo
• 推荐 - @ToDo
• 离线 - @ToDo
• 讨论页面 - @ToDo

MediaWiki REST API

文件

获取

返回有关文件的信息，包括以缩略图、预览和原始格式下载文件的链接。

  $wiki = new MediaWiki();
  $params = ['title'=>'The_Blue_Marble.jpg'];
  $res = $wiki->file()->get($params); 

页面

创建

创建维基页面。响应包括一个包含获取新页面API端点的位置头。

此端点是设计用于与OAuth扩展授权过程一起使用的。使用基于cookie的身份验证的调用者必须在请求体中添加CSRF令牌。要获取CSRF令牌，请参阅操作API。

@ToDo

更新

更新或创建维基页面。此端点是设计用于与OAuth扩展授权过程一起使用的。使用基于cookie的身份验证的调用者必须在请求体中添加CSRF令牌。要获取CSRF令牌，请参阅操作API。

要更新页面，您需要页面的最新修订ID和页面源代码。首先调用获取页面源代码端点，然后使用源代码和latest.id更新页面。如果latest.id不匹配页面的最新修订，API将自动解决可能的冲突。在编辑冲突的情况下，API返回409错误。

要创建页面，请从请求中省略latest.id。

@ToDo

获取

返回维基页面的标准页面对象，包括获取最新内容的HTML API路由、许可信息和最新修订信息。

  $wiki = new MediaWiki();
  $params = ['title'=>'Jupiter'];
  $res = $wiki->page()->get($params); 

获取离线版本

返回有关维基页面的信息，包括许可、最新修订和最新HTML内容。

  $wiki = new MediaWiki();
  $params = ['title'=>'Jupiter'];
  $res = $wiki->page()->getOffline($params); 

获取源代码

返回维基页面的内容，格式由content_model属性指定，包括许可信息和最新修订信息。

  $wiki = new MediaWiki();
  $params = ['title'=>'Jupiter'];
  $res = $wiki->page()->getSource($params); 

获取HTML

返回维基页面的最新内容，格式为HTML。

@ToDo = MediawikiResponse. 

  $wiki = new MediaWiki();
  $params = ['title'=>'Jupiter'];
  $res = $wiki->page()->getHtml($params); 

获取语言

搜索连接的维基中具有不同语言相同主题的页面。返回一个包含语言名称、语言代码和翻译页面标题的语言对象数组。

  $wiki = new MediaWiki();
  $params = ['title'=>'Jupiter'];
  $res = $wiki->page()->getLanguages($params); 

获取文件

返回有关维基页面中使用的媒体文件的信息。

  $wiki = new MediaWiki();
  $params = ['title'=>'Jupiter'];
  $res = $wiki->page()->getFiles($params); 

获取历史记录

返回关于维基页面最新修订版本的信息，以20个修订版本为一组，从最新修订版本开始。

响应包括API路由，用于浏览下一最旧、下一最新和最新修订版本段，让您可以滚动查看页面历史。

  $wiki = new MediaWiki();
  $params = ['title'=>'Jupiter'];
  $res = $wiki->page()->getHistory($params); 

获取历史记录数量

返回关于页面历史的数据。

  $wiki = new MediaWiki();
  $params = ['title'=>'Jupiter', 'type' => 'edits', 'from' => 384955912, 'to'=>406217369];
  $res = $wiki->page()->getHistoryCounts($params); 

修订

获取

返回单个修订版本的详细信息。

  $wiki = new MediaWiki();
  $params = ['id'=>1084994628];
  $res = $wiki->revision()->get($params); 

比较

返回数据，允许您显示两个修订版本之间的逐行比较。只有基于文本的维基页面可以进行比较。

  $wiki = new MediaWiki();
  $params = ['from' => 384955912, 'to' => 406217369];
  $res = $wiki->revision()->compare($params); 

搜索

页面

搜索维基页面标题和内容中的提供搜索词，并返回匹配的页面。

  $wiki = new MediaWiki();
  $params = ['q' => 'Jupiter', 'limit' => 5];
  $res = $wiki->search()->pages($params); 

自动完成页面标题

搜索维基页面标题，并返回标题开头与提供的搜索词之间的匹配项。您可以使用此操作进行自动建议相关页面的标题提示搜索。

  $wiki = new MediaWiki();
  $params = ['q' => 'Jupiter', 'limit' => 5];
  $res = $wiki->search()->autocompletePageTitle($params); 

Wikimedia REST API

页面内容

获取页面摘要

  $wiki = new MediaWiki();
  $params = ['title' => 'Jupiter'];
  $res = $wiki->pageContent()->getSummary($params); 

获取页面标题

  $wiki = new MediaWiki();
  $params = ['title' => 'Jupiter'];
  $res = $wiki->pageContent()->getTitle($params); 

请求参数验证

验证包使用 spatie/data-transfer-object 和 ekut/spatie-dto-validators。

每个操作的输入数组 $params 将与相关的 {...Request} 类（扩展 DataTransferObject）进行验证。所有请求 DTO 都非常严格。这意味着：如果 $params 包含某些未知属性，则会抛出 MediaWikiException。请参阅代码树中的 请求类。

错误处理

任何非成功的请求（状态码 >= 400）将抛出 MediaWikiException。

try{
    $res = $wiki->{ResourceName()}->{ActionName($params)}
} catch (\MediawikiSdkPhp\Exceptions\MediaWikiException $e) {
    echo $e->getCode();
    echo $e->getMessage();
    echo $e->getReason();
}

它扩展了主要的 PHP 异常类，并包含一个附加方法

  $e->getReason();

开发

需要 Docker 和 Docker-Compose。

初始化开发者环境

make init

运行测试

make sdk-test

运行 bash shell

make sdk-shell