README

变更日志

0.2.2 2022年12月3日添加了对 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 - 带有介词的当地格（locative）；
$declensionResult->To – куда — в направительном падеже (аллатив) с предлогом;
$declensionResult->From –откуда — в исходном падеже (аблатив) с предлогом.

用于解决歧义的标志

有些词可以有不同的变形，例如

姓氏Resnichenko男性变格，女性不变格；
Ростов在属格时如果是姓氏则是Ростовым，如果是城市则是Ростовом；
测试员在宾格时如果是人则是测试员，如果是仪器则是测试器。

为了提高变形质量，您可以通过标志向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类）
timestamp（整数）。

该方法返回对象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\СorrectionEntry 对象

单数 — 对象 Morpher\Ws3Client\Russian\CorrectionForms，包含单数形式；
复数 — 对象 Morpher\Ws3Client\Russian\CorrectionForms，包含复数形式；

不支持指定性别。

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

主格 (Nominative) — 主格形式文本；
属格 (Genitive) — 属格形式文本；
与格 (Dative) — 与格形式文本；
宾格 (Accusative) — 宾格形式文本；
工具格 (Instrumental) — 工具格形式文本；
前置格 (Prepositional) — 前置格形式文本；
位格 (Locative) — 位格形式文本；

对于乌克兰语

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

单数 — 对象 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，一个用于捷克语的变格库

morpher / ws3-client

维护者

详细信息

README

系统要求

安装

使用

俄语变格

用于解决歧义的标志

姓名、名字和姓氏的突出显示

数字的书写和与数字的协调

将数字书写为序数词

数字的书写

形容词的性别变形

形容词的形成

在文本中放置重音

乌克兰语的格变形

用于解决歧义的标志

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

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

剩余请求

用户词典

获取校正列表

对于俄语

对于乌克兰语

添加或修改更正

删除更正

错误处理

开发

启动测试

更新依赖关系

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

发布新版本

另请参阅