README

该项目允许PHP开发者使用

• MediaWiki REST API
• 和 Wikimedia REST API 在他们的PHP代码中。

安装

您可以通过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 将被抛出。请参阅代码树中的 Request 类。

错误处理

任何非成功请求（状态 >= 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