masterweber/morpher-ws3-php-client

PHP-клиент веб-сервиса "Морфер" 3.0

v0.3.1 2021-03-14 08:42 UTC

This package is auto-updated.

Last update: 2021-09-20 09:52:49 UTC


README

PHP-клиент веб-сервиса "Морфер" 3.0

GitHub Workflow Status GitHub release (latest by date) Packagist Downloads GitHub

Библиотека реализует следующие функции

(с помощью веб-сервиса "Морфер 3.0")

На русском языке:

На украинском языке:

На казахском языке:

Общие:

Пользовательский словарь

Веб-сервис поддерживает исправление склонения по требованию пользователя. Для этого имеются 3 метода:

Веб-сервис "Морфер 3.0" предусматривает бесплатное (с ограничениями) и платное использование. Подробнее смотрите на сайте проекта.

Установка

composer require masterweber/morpher-ws3-php-client

Использование

use Morpher\Morpher;

$morpher = new Morpher(
    'https://localhost', // по умолчанию https://ws3.morpher.ru
    'YOUR_TOKEN',        // по умолчанию null
    1.0                  // по умолчанию 3.0 сек
);

Можно вызвать конструктор без аргументов, в этом случае будут использоваться параметры по умолчанию.

use Morpher\Morpher;

$morpher = new Morpher();

Склонение по падежам на русском языке

Для склонения слов и словосочетаний используется метод russian->declension(string $phrase, string ...$flags):

$result = $morpher->russian->declension('Программист');

echo $result->genitive;         // Программиста
echo $result->plural->genitive; // Программистов

$result — объект DeclensionResult со следующими свойствами:

  • nominative — текст в именительном падеже;
  • genitive — текст в родительном падеже;
  • dative — текст в дательном падеже;
  • accusative — текст в винительном падеже;
  • instrumental — текст в творительном падеже;
  • prepositional — текст в предложном падеже;
  • plural — объект со свойствами-падежами для текста во множественном числе.

При использовании платного аккаунта на сервисе, определяются дополнительные свойства:

  • prepositional_O — предложный падеж с предлогом О/ОБ/ОБО, предлог выбирается автоматически;
  • gender — род (мужской, женский или средний);
  • where, locative — в местном падеже (локатив) с предлогом;
  • where_to — в направительном падеже (аллатив) с предлогом;
  • where_from, whence — в исходном падеже (аблатив) с предлогом.

Флаги для разрешения неоднозначностей

Есть слова, которые могут склоняться по-разному, например:

  • фамилия Резник склоняется у мужчин и не склоняется у женщин;
  • Ростов в творительном падеже будет Ростовым, если это фамилия, и Ростовом, если это город;
  • тестер в винительном падеже будет тестера, если это человек, и тестер, если имеется в виду прибор.

Для повышения качества склонения вы можете сообщить веб-сервису дополнительную информацию через флаги. Несколько флагов можно передать через запятую:

use Morpher\Russian\RussianClient;

$result = $morpher->russian->declension(
    'Слепов Сергей Николаевич', 
    RussianClient::FLAG_NAME, 
    RussianClient::FLAG_MASCULINE
);

echo $result->genitive;       // Слепова Сергея Николаевича
echo $result->fullName->name; // Сергей

Флаги поддерживаемые для russian->declension(string $phrase, string ...$flags):

  • RussianClient::FLAG_FEMININE — Женский род;
  • RussianClient::FLAG_MASCULINE — Мужской род;
  • RussianClient::FLAG_ANIMATE — Одушевлённое;
  • RussianClient::FLAG_INANIMATE — Неодушевлённое;
  • RussianClient::FLAG_COMMON — Нарицательное;
  • RussianClient::FLAG_NAME — ФИО.

Выделение в строке фамилии, имени и отчества

Если входная строка распознана как ФИО, то объект DeclensionResult будет содержать разбивку строки на фамилию, имя и отчество:

  • genitive — ФИО в родительном падеже;
  • dative — ФИО в дательном падеже;
  • accusative — ФИО в винительном падеже;
  • instrumental — ФИО в творительном падеже;
  • prepositional — ФИО в предложном падеже;
  • name — Имя в именительном падеже;
  • surname — Фамилия в именительном падеже;
  • patronymic — Отчество в именительном падеже.

Пропись чисел и согласование с числом

Метод russian->spell(int $number, string $unit) решает задачу получения прописи числа (тысяча сто двадцать пять) и согласование единицы измерения с предшествующем числом (1 попугай, 2 попугая, 5 попугаев):

$result = $morpher->russian->spell(235, 'рубль');

echo $result->n->genitive;    // двухсот тридцати пяти
echo $result->unit->genitive; // рублей

Комбинируя соответствующие падежные формы n и unit, можно получить вывод «суммы прописью» на любой вкус:

  • 235 рублей
  • Двести тридцать пять рублей
  • 235 (двести тридцать пять) рублей и т.п.

Пропись чисел в виде порядковых числительных

Метод russian->spellOrdinal(int $number, string $unit) похож на russian->spell(int $number, string $unit), но возвращает пропись числа в форме порядкового числительного:

$result = $morpher->russian->spellOrdinal(5, 'колесо');

echo $result->n->genitive;    // пятого
echo $result->unit->genitive; // колеса

Пропись дат

Метод russian->spellDate(DateTime $date) склоняет по падежам дату:

$date = new DateTime();
$result = $morpher->russian->spellDate($date);

echo $result->genitive;     // двадцать девятого июня две тысячи девятнадцатого года
echo $result->instrumental; // двадцать девятому июня две тысячи девятнадцатого года

Склонение прилагательных по родам

Метод russian->adjectiveGenders(string $adjective) склоняет данное ему прилагательное, преобразуя его из мужского рода в женский, средний и во множественное число:

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

echo $result->feminine; // уважаемая
echo $result->neuter;   // уважаемое
echo $result->plural;   // уважаемые

Требования к входному прилагательному:

  • Оно должно быть в мужском роде, в единственном числе.
  • Оно должно быть полным, т.е. "полный", а не "полон".
  • Оно должно быть одним словом. Внутри слова допустимы дефис и апостроф: рабоче-крестьянский, Кот-д'Ивуарский. Вокруг слова допустимы пробелы, кавычки и другие знаки.

Образование прилагательных

Метод russian->adjectivize(string $lemma) образует прилагательные от названий городов и стран: Москва – московский, Ростов – ростовский, Швеция – шведский, Греция – греческий.

Пример:

$result = $morpher->russian->adjectivize('Москва');

print_r($result); // ['московский']

Метод возвращает массив строк. Что они означают, описано здесь.

Расстановка ударений в текстах

Метод russian->addStressMarks(string $text) расставляет ударения в текстах на русском языке:

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

echo $result; // Три деви́цы под окно́м

Ударение отмечается символом с кодом U+0301, который вставляется сразу после ударной гласной. Односложные слова не получают знака ударения, за исключением случаев, когда предлог или частица несет на себе ударение: за́ руку, не́ за что. Варианты прочтения разделяются вертикальной чертой, например:

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

echo $result; // Бе́лки|Белки́ пита́ются бе́лками|белка́ми

Склонение по падежам на украинском языке

Украинский вариант склонения — метод ukrainian->declension(string $phrase, string ...$flags):

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

echo $result->genitive; // Крутько Катерини Володимирівни
echo $result->dative;   // Крутько Катерині Володимирівні
echo $result->vocative; // Крутько Катерино Володимирівно

$result — объект DeclensionResult со следующими свойствами:

  • nominative — текст в именительном падеже;
  • genitive — текст в родительном падеже;
  • dative — текст в дательном падеже;
  • accusative — текст в винительном падеже;
  • instrumental — текст в творительном падеже;
  • prepositional — текст в местном падеже;
  • vocative — текст в звательном падеже.

При использовании платного аккаунта на сервисе, определяются дополнительные свойства:

  • gender — род (чоловічий, жіночий);

Украинская версия пока обрабатывает только имена, фамилии и отчества.

Флаги для разрешения неоднозначностей

use Morpher\Ukrainian\UkrainianClient;

$result = $morpher->ukrainian->declension('Карен', UkrainianClient::FLAG_FEMININE);

echo $result->genitive; // Карен (женское имя не склоняется)

Флаги поддерживаемые для ukrainian->declension(string $phrase, string ...$flags):

  • UkrainianClient.FLAG_FEMININE — Женский род;
  • UkrainianClient.FLAG_MASCULINE — Мужской род;
  • UkrainianClient.FLAG_NEUTER — Средний род;
  • UkrainianClient.FLAG_PLURAL — Множественное число.

Пропись чисел и согласование с числом на украинском языке

Метод ukrainian->spell(int $number, string $unit) решает задачу получения прописи числа (одна тисяча сто двадцять п'ять) и согласование единицы измерения с предшествующем числом (один рубль, два рубля, п'ять рублів):

$result = $morpher->ukrainian->spell(235, 'рубль');

echo $result->n->genitive;    // двохсот тридцяти п'яти
echo $result->unit->genitive; // рублів

Склонение по падежам, числам и лицам на казахском языке

Для склонения слов и словосочетаний используется метод qazaq->declension(string $phrase):

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

echo $result->genitive;                            // менеджердің
echo $result->plural->genitive;                    // менеджерлердің
echo $result->plural->firstPersonPlural->genitive; // менеджерлеріміздің

$result — объект DeclensionResult со следующими свойствами:

  • nominative — текст в именительном падеже;
  • genitive — текст в родительном падеже;
  • dative — текст в дательно-направительном падеже;
  • accusative — текст в винительном падеже;
  • ablative — текст в исходном падеже;
  • locative — текст в местном падеже;
  • instrumental — текст в творительном падеже;
  • plural — возвращает объект со свойствами-падежами для текста во множественном числе.

Остаток запросов

Метод getQueriesLeft() возвращает остаток запросов на данный момент. Лимит на запросы восстанавливается в 00:00 UTC.

$result = $morpher->getQueriesLeft();

echo $result; // 100

Получить список исправлений

Для того чтобы получить список всех исправлений, нужно использовать метод russian->userDict->getAll() или ukrainian->userDict->getAll():

$result = $morpher->russian->userDict->getAll();

print_r($result); // Массив с объектами CorrectionEntry

Объект СorrectionEntry со следующими свойствами:

  • singular — объект CorrectionForms с формами в единственном числе;
  • plural — объект CorrectionForms с формами во множественном числе;
  • gender — род (мужской, женский или средний).

Объект CorrectionForms со следующими свойствами:

  • nominative — текст в именительном падеже;
  • genitive — текст в родительном падеже;
  • dative — текст в дательном падеже;
  • accusative — текст в винительном падеже;
  • instrumental — текст в творительном падеже;
  • prepositional — текст в предложном падеже;
  • locative — текст в местном падеже;

Для украинского языка:

Объект СorrectionEntry со следующими свойствами:

  • singular — объект CorrectionForms с формами в единственном числе;
  • gender — род (чоловічий, жіночий).

Объект CorrectionForms со следующими свойствами:

  • nominative — текст в именительном падеже;
  • genitive — текст в родительном падеже;
  • dative — текст в дательном падеже;
  • accusative — текст в винительном падеже;
  • instrumental — текст в творительном падеже;
  • prepositional — текст в местном падеже;
  • vocative — текст в звательном падеже.

Добавить или изменить исправление

Для добавления или изменения исправления использовать метод russian->userDict->addOrUpdate(CorrectionEntry $entry).

use Morpher\Russian\CorrectionEntry;
use Morpher\Russian\CorrectionForms;

$singular = new CorrectionForms();
$singular->nominative = 'Кошка';
$singular->dative = 'Пантере';

$plural = new CorrectionForms();
$plural->dative = 'Пантерам';

$entry = new CorrectionEntry();

$morpher->russian->userDict->addOrUpdate($entry); // true

Для украинского языка:

use Morpher\Ukrainian\CorrectionEntry;
use Morpher\Ukrainian\CorrectionForms;

$singular = new CorrectionForms();
$singular->nominative = 'Кiшка';
$singular->dative = 'Пантерi';

$entry = new CorrectionEntry();

$morpher->ukrainian->userDict->addOrUpdate($entry); // true

Удаление исправления

Для того чтобы удалить исправление, достаточно передать строку в именительном падеже в метод russian->userDict->remove(string $nominativeForm):

$morpher->russian->userDict->remove('Кошка'); // true

Для украинского языка:

$morpher->ukrainian->userDict->remove('Кiшка'); // true

Разработка

PHP: Убедитесь, что установлена версия PHP не ниже ^7.4. Проверить это можно с помощью php -v.

Установка

Сделайте форк репозитория morpher-ws3-php-client.

Затем выполните:

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

Запуск тестов

$ composer test

Выпуск нового релиза

Примерно через минуту новый пакет должен появиться на packagist.org.

License

MIT