README

A simple PHP library for declining Ukrainian nouns and phrases. This library provides a straightforward way to get the correct grammatical form of a noun for any of the seven Ukrainian cases, in both singular and plural forms.

Installation

Install the library via Composer:

composer require ukrainian-declension/core

Basic Usage

The easiest way to use the library is by calling the static decline method.

use UkrainianDeclension\UkrainianDeclension;
use UkrainianDeclension\Enums\GrammaticalCase;
use UkrainianDeclension\Enums\Number;

// Decline a single word
$declinedWord = UkrainianDeclension::decline('книга', GrammaticalCase::GENITIVE, Number::SINGULAR);
echo $declinedWord; // Outputs: книги

// Decline a full name
$declinedName = UkrainianDeclension::decline('Петренко Олексій Іванович', GrammaticalCase::DATIVE, Number::SINGULAR);
echo $declinedName; // Outputs: Петренку Олексію Івановичу

Usage in Laravel

This library includes a Service Provider and Facade for easy integration with Laravel applications.

The provider and facade will be auto-discovered by Laravel.
You can use the Declensioner facade directly or inject the DeclensionerContract anywhere in your application.

Using the Facade

use UkrainianDeclension\Facades\Declensioner;
use UkrainianDeclension\Enums\GrammaticalCase;
use UkrainianDeclension\Enums\Number;

// Decline a phrase
$declinedPhrase = Declensioner::decline('молодший лейтенант', GrammaticalCase::INSTRUMENTAL, Number::SINGULAR);
echo $declinedPhrase; // Outputs: молодшим лейтенантом

// Decline a position title: only the head group changes
$position = Declensioner::decline('Електрик-моторист обслуги взводу зв\'язку військової частини А0000', GrammaticalCase::GENITIVE, Number::SINGULAR);
echo $position; // Outputs: Електрика-моториста обслуги взводу зв'язку військової частини А0000

Using Dependency Injection

use UkrainianDeclension\Contracts\DeclensionerContract;
use UkrainianDeclension\Enums\GrammaticalCase;
use UkrainianDeclension\Enums\Gender;
use UkrainianDeclension\Enums\Number;

class MyController
{
    private $declensioner;

    public function __construct(DeclensionerContract $declensioner)
    {
        $this->declensioner = $declensioner;
    }

    public function showDeclinedWord()
    {
        $word = 'книга';

        // Decline to Genitive Singular: "книги"
        $declined_singular = $this->declensioner->decline($word, GrammaticalCase::GENITIVE, Number::SINGULAR);

        // Decline to Nominative Plural: "книги"
        $declined_plural = $this->declensioner->decline($word, GrammaticalCase::NOMINATIVE, Number::PLURAL);

        echo $declined_singular; // Outputs: книги
        echo $declined_plural; // Outputs: книги
    }
}

Gender Guessing

The library can automatically guess the gender of a noun or a name within a phrase. For names, it often identifies gender by the patronymic (e.g., words ending in -ович for masculine, -івна for feminine). For single words, it uses endings and a list of exceptions.

This means you can often omit the Gender parameter.

// The library will correctly guess that "книга" is feminine.
$declined = UkrainianDeclension::decline('книга', GrammaticalCase::GENITIVE, Number::SINGULAR);

// The library will guess the gender is masculine from the patronymic 'Іванович'.
$declinedName = UkrainianDeclension::decline('Петренко Олексій Іванович', GrammaticalCase::DATIVE, Number::SINGULAR);

However, you can still provide the gender for ambiguous words or to ensure accuracy.

How phrases are declined

decline() inspects the shape of the input:

Input	What changes	Example (genitive)
Single word	the word	`майстер` → `майстра`, `стрілець` → `стрільця`
Position or unit title	only the head group: leading adjectives + the head noun (both parts of a hyphenated head)	`Старший електрик-моторист обслуги взводу` → `Старшого електрика-моториста обслуги взводу`
Personal name (`Прізвище Ім'я По батькові`, `Ім'я Прізвище`, ALL-CAPS surname)	every part; feminine surnames in a consonant / `-ко` stay unchanged	`Кравчук Олена Іванівна` → `Кравчук Олени Іванівни`
Military rank + name	the rank and every part of the name	`старший лейтенант ДЖУРЯК Роман Михайлович` → `старшого лейтенанта ДЖУРЯКА Романа Михайловича`

Dependent words that are already in an oblique case (обслуги, 2 відділення, військової частини А5101) are never touched, so a fragment such as матеріального забезпечення групи is returned unchanged. Appositions after a dash are declined as separate head groups (Начальник штабу – перший заступник командира → Начальника штабу – першого заступника командира).

Whitespace (including non-breaking spaces), punctuation attached to words, apostrophe variants (', ’, `), numerals (2, 1-го), unit codes (А0000) and short abbreviations (ЗСУ, ст.) are preserved.

Gender and number

Gender describes the person for names. For position titles the grammatical gender of the head noun is used, so Старший сержант declines as masculine even when Gender::FEMININE is passed; feminine titles (Санітарка, Старша медична сестра) decline as feminine.
Number::PLURAL expects the input in the singular (старший солдат → старших солдатів); a masculine plural input (старші сержанти) is also accepted.
Locative singular of animate masculine nouns uses -ові/-еві (командирові, кухареві); hyphenated compounds use the short -у/-ю (електрику-мотористу).

Known limitations

The genitive -а/-у choice for inanimate masculine nouns is lexical; the library covers common military and administrative nouns (взводу, штабу, наказу) and defaults to -а otherwise.
Feminine plural input (медичні сестри) is not lemmatised; pass the singular form with Number::PLURAL.
Possessive adjectives (батьків, Шевченків) are declined as nouns.

ukrainian-declension / core

Package info

Security

Statistics