README

A PHP port of the shevchenko.js library for declining Ukrainian anthropomorphic names (given names, patronymics, family names) and other proper nouns.

This library provides accurate inflection rules for Ukrainian language grammatical cases and includes support for military ranks and appointments through extensions.

Installation

Install the library via Composer:

composer require enkot/shevchenko

Basic Usage

Declining Names

You can inflect a full name into a specific grammatical case. The library handles gender and the component parts of the name.

use Shevchenko\Shevchenko;
use Shevchenko\Language\GrammaticalGender;
use Shevchenko\Language\GrammaticalCase;

$shevchenko = new Shevchenko();

// create input
$input = [
    'gender' => GrammaticalGender::MASCULINE
    'givenName' => 'Тарас',
    'patronymicName' => 'Григорович',
    'familyName' => 'Шевченко'
];

// Inflect to Dative case (Давальний відмінок)
$dativeoutput = $shevchenko->inDative($input);

echo $dativeoutput['givenName'];       // Тарасу
echo $dativeoutput['patronymicName'];  // Григоровичу
echo $dativeoutput['familyName'];      // Шевченку

// Or using generic method
$genitiveOutput = $shevchenko->inGrammaticalCase(GrammaticalCase::GENITIVE, $input);

Supported Grammatical Cases

The library supports all 7 Ukrainian grammatical cases:

inNominative() - Називний (who? what?)
inGenitive() - Родовий (whom? what?)
inDative() - Давальний (to whom? to what?)
inAccusative() - Знахідний (whom? what?)
inAblative() - Орудний (by whom? by what?)
inLocative() - Місцевий (on whom? on what?)
inVocative() - Кличний (addressing)

Gender Detection

The library can attempt to detect the grammatical gender of a name based on the suffix of the given name or patronymic.

use Shevchenko\Shevchenko;

$shevchenko = new Shevchenko();

$input = [
    'givenName' => 'Тарас',
    'patronymicName' => 'Григорович',
    'familyName' => 'Шевченко'
];

$gender = $shevchenko->detectGender($input);

echo $gender->value; // masculine

Extensions

Military Extension

The library includes a built-in military extension for correctly declining military ranks and appointments.

use Shevchenko\Shevchenko;
use Shevchenko\Military\MilitaryExtension;
use Shevchenko\Language\GrammaticalCase;

$shevchenko = new Shevchenko();
// Register the extension
$shevchenko->registerExtension(new MilitaryExtension());

$input = [
    'gender' => 'masculine',
    'familyName' => 'Шевченко',
    'givenName' => 'Тарас',
    'patronymicName' => 'Григорович',
    // Extension fields
    'militaryRank' => 'солдат',
    'militaryAppointment' => 'помічник гранатометника',
];

// Inflect everything in one go (e.g., to Genitive/Родовий)
$output = $shevchenko->inGenitive($input);

echo $output['militaryRank'];        // солдата
echo $output['militaryAppointment']; // помічника гранатометника
echo $output['familyName'];          // Шевченка

Requirements

PHP 8.1 or higher
ext-json

License

MIT

enkot / shevchenko

Maintainers

Details