README

变更历史

0.2.2 03.12.2022 添加了对 PHP 7.4 的支持（之前代码仅在 PHP 8.0+ 上执行）

该库实现以下功能（通过 "Morfer 3.0" 网络服务）

俄语

单词和短语变格
在行中突出显示姓氏、名字和父名
数字书写和单位量词的变格（3个新字母，10个评论）
以序数词的形式书写数字（例如，“一百一千米”）
以任何变格书写日期（例如，“二零零一年五月五日”）
形容词变格
从城市和国家名称派生形容词
文本中的重音标记
用户词典以纠正

乌克兰语

变格
数字书写和单位量词的变格（3 рупля，10 коментарів）
用户词典以纠正

哈萨克语

变格、数字和人称

通用

当日剩余请求数
错误处理

"Morfer 3.0" 网络服务提供免费（有限制）和付费使用。有关详细信息，请参阅项目网站。

系统要求

PHP 7.4 及以上版本
composer

安装

如果您的项目中没有 composer.json 文件，则需要执行

$ composer init

并回答程序提出的问题（项目名称等）。请注意 minimum-stability 参数 - 它不应高于您将在项目中安装的 morpher 版本的指定值。如果无法安装包，请尝试在 composer.json 文件中指定： "minimum-stability": "dev"。

将创建 composer.json 文件和 vendor 文件夹。
执行以下命令

$  composer require morpher/ws3-client

使用

<?php  
require_once __DIR__."/vendor/autoload.php";  
use Morpher\Ws3Client\Morpher;  
$base_url = 'https://ws3.morpher.ru';  
$token = "";  
$morpher = new Morpher($base_url, $token);  
$declensionResult = $morpher->russian->Parse('трамвай');
print_r($declensionResult);

其中 $token=""; 在引号内指定在 https://morpher.ru 网站上注册时获得的令牌。
如果令牌为空，则服务将以免费版本的限制运行。
可以无参数调用构造函数，在这种情况下将使用默认参数。

俄语变格

方法 $morpher->russian->Parse($lemma,$flags) 解决单词或短语的变格问题；

输入参数

字符串 - 俄语单词或短语。
标志数组（可选参数）。标志接受来自类 Morpher\Ws3Client\Russian\Flags 的常数值。

示例

$declensionResult = $morpher->russian->Parse('фраза на русском');

$declensionResult — 一个具有以下属性的 Morpher\Ws3Client\Russian\DeclensionResult 对象

$declensionResult->Nominative — 名词性变格的文本；
$declensionResult->Genitive — 生成性变格的文本；
$declensionResult->Dative — 介词性变格的文本；
$declensionResult->Accusative — 受词性变格的文本；
$declensionResult->Instrumental — 创造性变格的文本；
$declensionResult->Prepositional — 介词性变格的文本；
$declensionResult->Plural — 具有变格属性的文本的复数对象，例如 $declensionResult->Plural->Nominative .

在使用付费账户时，服务将确定额外的属性

$declensionResult->PrepositionalWithO — 带有介词 О/ОБ/ОБО 的介词性变格，介词自动选择；
$declensionResult->Gender — 性别。类型 – 字符串。接受来自类 Morpher\Ws3Client\Russian\Gender 的常数值，共 4 种 -
- Gender::Masculine 男
- Gender::Feminine 女
- Gender::Neuter 中性
- Gender::Plural 复数
$declensionResult->Where — 在带介词的局部变格（locativ）中；
$declensionResult->To – куда — в направительном падеже (аллатив) с предлогом;
$declensionResult->From –откуда — в исходном падеже (аблатив) с предлогом.

用于解决歧义性的标志

有些词可能有不同的变格，例如

姓Resnik男性变格，女性不变格；
如果Ростов是姓氏，那么它将是Ростовым；如果它是城市，它也将是Ростовым；
如果指人，则tester在宾语落格中将是testера，如果指仪器，则是tester。

为了提高变格质量，您可以通过标志向Web服务提供额外信息。标志接受来自类Morpher\Ws3Client\Russian\Flags的常量值。标志需要以数组形式传递

use Morpher\Ws3Client\Russian\Flags;  
$morpher->russian->Parse('Резник', [Flags::Name, Flags::Masculine]);

$morpher->russian->Parse的标志

Flags::Feminine — 女性
Flags::Masculine — 男性
Flags::Animate — 有生命的
Flags::Inanimate — 无生命的
Flags::Common — 普通名词
Flags::Name — 姓名

在句子中突出显示姓氏、名字和父名

如果输入字符串被识别为姓名，则对象$declensionResult->FullName将包含字符串的姓氏、名字和父名的分割

$declensionResult->FullName->Name - 名字；
$declensionResult->FullName->Surname - 姓氏；
$declensionResult->FullName->Patronymic – 父名。

数字的书写和与数字的一致性

方法$morpher->russian->Spell($number, $unit)解决获取数字（一千二百二十五）和与先前数字（1只鹦鹉，2只鹦鹉，5只鹦鹉）一致的书写问题。

输入参数

$number – 整数；
$unit – 字符串。

该方法返回对象Morpher\Ws3Client\Russian\NumberSpellingResult，
包含属性NumberDeclension和UnitDeclension。这两个属性都包含所有格的变格

$numberSpellingResult=$morpher->russian->Spell(235, 'рубль');  
print $numberSpellingResult->NumberDeclension->Dative; // двумстам тридцати пяти  
print $numberSpellingResult->UnitDeclension->Dative; // рублям

将数字书写为序数词

方法$morpher->russian->SpellOrdinal($number, $unit)解决将数字以序数词形式书写的问题。

输入参数

$number – 整数；
$unit – 字符串。

该方法返回对象Morpher\Ws3Client\Russian\NumberSpellingResult。示例

$numberSpellingResult =$morpher->russian->SpellOrdinal(5, 'колесо');  
print $numberSpellingResult->NumberDeclension->Dative; //пятому  
print $numberSpellingResult->UnitDeclension->Dative; //колесу

数字的书写

方法$morpher->russian->SpellDate($date)解决日期的书写和变格问题。日期可以是

格式为"2019-06-29"的字符串；
实现DateTimeInterface的对象（例如DateTime类）；
时间戳（整数）。

该方法返回对象Morpher\Ws3Client\Russian\DateSpellingResult。示例

$dateSpellingResult = $morpher->russian->SpellDate('2019-06-29');  
print $dateSpellingResult->Genitive;  // двадцать девятого июня две тысячи девятнадцатого года  
print $dateSpellingResult->Dative; // двадцать девятому июня две тысячи девятнадцатого года  
print $dateSpellingResult->Instrumental; // двадцать девятым июня две тысячи девятнадцатого года

形容词的性别变格

方法$morpher->russian->AdjectiveGenders($adjective)将给定的形容词变格，将其从男性性别转换为女性、中性和复数。

输入参数 – 形容词字符串。输入形容词的要求

它应该是男性性别，单数。
它应该是完整的，即"完整的"，而不是"完整"。
它应该是一词，单词内部可以有连字符和撇号：工人-农民，科特迪瓦；单词周围可以有空白、引号和其他符号。

该方法返回对象Morpher\Ws3Client\Russian\AdjectiveGenders

$adjectiveGenders =$morpher->russian->AdjectiveGenders('уважаемый');  

print $adjectiveGenders->Feminine;      // уважаемая  
print $adjectiveGenders->Neuter;        // уважаемое  
print $adjectiveGenders->Plural;        // уважаемые

形容词的形成

方法$morpher->russian->Adjectivize($lemma)从城市和国家名称形成形容词：莫斯科 – 莫斯科的，罗斯托夫 – 罗斯托夫的，瑞典 – 瑞典的，希腊 – 希腊的。输入参数 – 字符串。方法返回字符串数组。它们的意义在本站这里描述。
示例

$adjectives=$morpher->russian->Adjectivize('Москва');  
print   $adjectives[0]; // московский

在文本中设置重音

方法$morpher->russian->addStressMarks($text)在俄语文本中设置重音。输入参数 – 字符串。方法返回与输入字符串类似但添加了重音符号和 над Ё的点号的字符串。字符串可以很长。

$result=$morpher->russian->addStressMarks('Три девицы под окном');  
print $result; // Три деви́цы под окно́м

重音用代码为 U+0301 的符号表示，该符号直接插入到重音元音之后。单音节词通常不带重音符号，除非介词或助词本身带有重音：за́ руку，не́ за что。不同的读法用竖线分隔，例如

$result=$morpher->russian->addStressMarks('Белки питаются белками');  
print $result; // Бе́лки|Белки́ пита́ются бе́лками|белка́ми

乌克兰语的格变化

乌克兰语的格变化方法 — $morpher->ukrainian->Parse($lemma, $flags)。

输入参数

包含乌克兰语单词或短语的字符串。
一个可选的标志数组，它接受来自类 Morpher\Ws3Client\Ukrainian\Flag 的常量值。

该方法返回一个 Morpher\Ws3Client\Ukrainian\DeclensionResult 对象

$declensionResult=$morpher->ukrainian->Parse('Крутько Катерина Володимирiвна');  

print $declensionResult->Genitive; // Крутько Катерини Володимирівни  
print $declensionResult->Dative;   // Крутько Катерині Володимирівні  
print $declensionResult->Vocative; // Крутько Катерино Володимирівно

Morpher\Ws3Client\Ukrainian\DeclensionResult 对象具有以下属性

Nominative — 名词性格的文本；
Genitive — 属格的文本；
Dative — 与格的文本；
Accusative — 宾格的文本；
Instrumental — 介词格的文本；
Prepositional — 地点格的文本；
Vocative — 呼唤格的文本。

在付费访问中返回额外的属性

Gender — 性别，类型 — 字符串，接受来自类 Morpher\Ws3Client\Ukrainian\Gender 的常量值，选项
- Gender::Masculine (Чоловічий)
- Gender::Feminine (Жіночий)
- Gender::Neuter (Середній)
- Gender::Plural (Множина)

用于解决歧义性的标志

示例

use  Morpher\Ws3Client\Ukrainian\Flags;
$declensionResult=$morpher->ukrainian->Parse('Карен', [Flags::Feminine]);  
print $declensionResult->Genitive; // Карен (женское имя не склоняется)

函数 $morpher->ukrainian->Parse($lemma, $flags) 支持的标志

Flags::Feminine — 雌性
Flags::Masculine — 雄性
Gender::Neuter — 中性
Gender::Plural — 复数

乌克兰语的数字书写和数与数的协调

方法 $morpher->ukrainian->Spell($number, $unit) 解决了获取数字的书写形式（一千一百二十五）和单位与前置数的协调问题（一卢布，二卢布，五卢布）。

输入参数

$number – 整数；
$unit – 字符串。

该方法返回一个 Morpher\Ws3Client\Ukrainian\NumberSpellingResult 对象，
包含属性 NumberDeclension 和 UnitDeclension。这两个属性都包含所有格的变化

$spellingResult=$morpher->ukrainian->Spell(235, 'рубль');  
print $spellingResult->NumberDeclension->Genitive; // двохсот тридцяти п'яти  
print $spellingResult->UnitDeclension->Genitive;   // рублів

哈萨克语的格、数和人称变化

使用方法 $morpher->qazaq->Parse($phrase) 来变化单词和短语。
输入参数 — 哈萨克语单词或短语。该方法返回一个 Morpher\Ws3Client\Qazaq\DeclensionResult 对象。

示例

$declensionResult=$morpher->qazaq->Parse('бала');
print_r($declensionResult);

该对象具有复杂结构。

该对象包含7个格，以及8个单数变化的人称形式，每个形式包含7个格。

$declensionResult->Genitive  
$declensionResult->FirstPerson->Genitive  
$declensionResult->SecondPerson->Accusative  
…  
$declensionResult->ThirdPersonPlural->Dative

还包含一个名为 Plural 的对象，其中包含7个复数格，以及8个复数变化的人称形式，每个形式包含7个格

$declensionResult->Plural->Locative  
$declensionResult->Plural->FirstPerson->Locative  
$declensionResult->Plural->SecondPerson->Nominative  
…  
$declensionResult->Plural->ThirdPersonPlural->Dative

示例

$declensionResult = $morpher->qazaq->Parse('менеджер');  

print $declensionResult->Genitive;      // менеджердің  
print $declensionResult->Plural->Genitive;  // менеджерлердің  
print $declensionResult->Plural->FirstPerson->Genitive; // менеджерлеріміздің

Morpher\Ws3Client\Qazaq\DeclensionResult 对象的属性

单数格属性

Nominative - атау — 名词性格的文本；
Genitive - ілік — 属格的文本；
Dative - барыс — 与格的文本；
Accusative - табыс — 宾格的文本；
Ablative - шығыс — 出源格的文本；
Locative - жатыс — 地点格的文本；
Instrumental - көмектес — 介词格的文本；

属性 - 单数的人称形式（每个都有自己的格）

FirstPerson - "менің"
SecondPerson - "сенің"
SecondPersonRespectful - "сіздің"
ThirdPerson - "оның"
FirstPersonPlural - "біздің"
SecondPersonPlural - "сендердің"
SecondPersonRespectfulPlural - "сіздердің"
ThirdPersonPlural - "олардың"

复数属性

Plural - көпше — 返回一个具有属性-格和属性-人称形式的类似对象，用于复数文本。

剩余请求

方法 $morpher->getQueriesLeftForToday() 返回当前剩余的请求数。请求限制在 UTC 00:00 恢复。

print  $morpher->getQueriesLeftForToday(); // 939

用户词典

Web服务支持根据用户需求进行词形变化修正。为此，有3种方法

获取所有添加的修正列表；
添加或修改修正；
删除修正。

获取修正列表

要获取所有修正的列表，需要使用以下方法

$rus=$morpher->russian->userDict->GetAll();   // Morpher\Ws3Client\Russian\СorrectionEntry  
$ukr=$morpher->ukrainian->userDict->GetAll(); // Morpher\Ws3Client\Ukrainian\СorrectionEntry

该方法返回对应语言（俄语、乌克兰语）命名空间中的CorrectionEntry对象数组。

对于俄语

具有以下属性的Morpher\Ws3Client\Russian\CorrectionEntry对象

singular — 单数形式的对象Morpher\Ws3Client\Russian\CorrectionForms；
plural — 复数形式的对象Morpher\Ws3Client\Russian\CorrectionForms；

不支持指定性别。

具有以下属性的Morpher\Ws3Client\Russian\CorrectionForms对象

主格（Nominative）— 主格形式文本；
属格（Genitive）— 属格形式文本；
与格（Dative）— 与格形式文本；
宾格（Accusative）— 宾格形式文本；
工具格（Instrumental）— 工具格形式文本；
前置格（Prepositional）— 前置格形式文本；
地方格（Locative）— 地方格形式文本；]

对于乌克兰语

具有以下属性的Morpher\Ws3Client\Ukrainian\CorrectionEntry对象

singular — 单数形式的对象Morpher\Ws3Client\Ukrainian\CorrectionForms；

不支持指定性别。

具有以下属性的Morpher\Ws3Client\Ukrainian\CorrectionForms对象

主格（Nominative）— 主格形式文本；
属格（Genitive）— 属格形式文本；
与格（Dative）— 与格形式文本；
宾格（Accusative）— 宾格形式文本；
工具格（Instrumental）— 工具格形式文本；
前置格（Prepositional）— 前置格形式文本；
呼唤格（Vocative）— 呼唤格形式文本。

添加或修改修正

要添加或修改修正，请使用方法$morpher->russian->userDict->AddOrUpdate($entry)，
或类似地
$morpher->ukrainian->userDict->AddOrUpdate($entry):

$correctionEntry=new \Morpher\Ws3Client\Russian\CorrectionEntry();  
$correctionEntry->Singular->Nominative="чебуратор";  
$correctionEntry->Singular->Locative='в чебураторке';  
$correctionEntry->Plural->Locative='в чебураториях';  
$morpher->russian->userDict->AddOrUpdate($correctionEntry);

删除修正

要删除修正，只需将主格形式的字符串传递给方法

$morpher->russian->userDict->Remove($nominativeForm);

或类似地

$morpher->ukrainian->userDict->Remove($nominativeForm);

示例

$morpher->russian->userDict->Remove('чебуратор');

错误处理

在调用Web服务功能时可能会出现错误，例如，连接失败或参数值不合法。

库通过抛出异常来报告错误。

Web服务中的任何函数都可能抛出的异常都被组织在一个以SystemError类为根的层次结构中。

SystemError
- ConnectionError - 包括所有连接错误，如
  - 超时
  - SSL证书错误
  - DNS错误和其他
- InvalidServerResponse - 服务器响应不正确
  - UnknownErrorCode - 未知错误代码
- ServiceDenied - 拒绝执行操作
  - IpBlocked - IP地址被封锁
  - RequestsDailyLimit - 超过请求限制
- AuthenticationError - 认证错误
  - TokenNotFound - 没有在系统中注册此令牌
  - TokenIncorrectFormat - 令牌格式不正确

此外，每个函数都可能抛出自己的异常，这些异常在PHP-Doc中列出。

开发

本节是为那些想帮助开发这个库的人准备的。

对morpher-ws3-php-client仓库进行分叉。
然后执行

$ git clone https://github.com/<your-github-username>/morpher-ws3-php-client  
$ cd morpher-ws3-php-client  
$ composer install

应该会出现一个名为vendor的文件夹。

启动测试

启动单元测试

$ vendor\bin\phpunit tests\unit

要启动集成测试，需要设置秘密令牌，否则测试将部分失败。有两种设置令牌的方法

适用于本地启动。创建一个名为tests/integration/secret.php的文件，在其中声明一个常量
```
<?php  
DEFINE("MORPHER_RU_TOKEN", "xxxxx-xxxxxx-xxxxxxx");
```
适用于在GitHub Actions中启动。在GitHub Actions中，在Secrets部分创建一个环境变量MORPHER_RU_TOKEN，并将令牌保存在其中。

启动集成测试

$ vendor\bin\phpunit tests\integration

更新依赖关系

$ composer update

更新composer autoload自动加载（在项目中新创建每个php文件后）

$ composer dump-autoload -o

发布新版本

在composer.json中增加版本号。
在GitHub上添加新版本。
在 https://packagist.org.cn 的个人面板上发布软件包。

另请参阅

masterweber/morpher-ws3-php-client，由 MasterWeber 提供的 ws3.morpher.ru 的非官方客户端
doctrine/inflector，一个流行的英语复数化库
Mikulas/inflection，捷克语的变格库

andrey-dvoryadkin / morpher-ws3-php7.3-client

维护者

详细信息

README

系统要求

安装

使用

俄语变格

用于解决歧义性的标志

在句子中突出显示姓氏、名字和父名

数字的书写和与数字的一致性

将数字书写为序数词

数字的书写

形容词的性别变格

形容词的形成

在文本中设置重音

乌克兰语的格变化

用于解决歧义性的标志

乌克兰语的数字书写和数与数的协调

哈萨克语的格、数和人称变化

剩余请求

用户词典

获取修正列表

对于俄语

对于乌克兰语

添加或修改修正

删除修正

错误处理

开发

启动测试

更新依赖关系

更新composer autoload自动加载（在项目中新创建每个php文件后）

发布新版本

另请参阅