README

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

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

(с помощью веб-сервиса "Морфер 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

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

Добавить новый релиз на GitHub.

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

License

MIT

masterweber / morpher-ws3-php-client

Maintainers

Details

README

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

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

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

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

Общие:

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

Установка

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

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

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

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

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

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

Пропись дат

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

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

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

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

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

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

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

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

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

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

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

Разработка

Установка

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

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

License