Lithuanian Names Declension Laravel Package

Getting Started

Reality check first. This is a 2015-era Symfony bundle (not a Laravel package), last released in October 2015, with 3 stars and zero dependents. Treat it as MIT-licensed source code you vendor into your app, not as a dependency you require and trust. Confirm the license file is actually present before you lean on it commercially.

Minimal steps:

1. composer require jokubasr/lithuanian-names-declension --dry-run first. Because it is a Symfony bundle, it likely requires symfony/framework-bundle or several Symfony 2.x components, which will collide with Laravel's illuminate/* graph. If the dry run explodes, do not fight it — clone the repo instead.
2. Clone the repo and read, in this order: composer.json (autoload map + PHP constraint), the bundle class (*Bundle.php), Resources/config/services.yml (the service id and constructor args), then the class that actually does the work — usually something like Declension, Decliner, or NameDeclension under Model/, Service/, or lib/.
3. Copy only the declension class (and any small helper it depends on) into app/Support/LithuanianNames/. Strip the DI wiring; you almost certainly don't need it.

First use case — the one that justifies the whole exercise: producing grammatically correct Lithuanian in outbound text. "Sveiki, Jonai" in a greeting, "Sąskaita išrašyta Jonui Jonaičiui" on an invoice, "Padėka Rasai Kazlauskaitei" in a notification. Nominative-only text reads as machine-generated to any native speaker, so this is a real quality win if your product surfaces Lithuanian names.

// FQCN and signature must be confirmed from src/ — this is the shape to expect
$decliner = new \JokubasR\NamesDeclension\Decliner();

echo $decliner->decline('Jonas', 'Jonaitis', 'dative');
// Jonui Jonaičiui

Implementation Patterns

Wrap it, immediately. Create a single NameDeclension class in your app that owns the third-party object and exposes only what you need:

final class NameDeclension
{
    public function __construct(private $decliner) {}

    public function decline(string $first, ?string $last, Case $case): DeclinedName
    {
        // normalize, guard, call, catch, fall back to input
    }
}

This is not ceremony — it is your escape hatch when you inevitably fork or replace the library. Nothing else in your appbase should reference the package namespace.

Model cases as a PHP enum, not strings. Map your enum to whatever the package expects in one place. Lithuanian has seven cases; you will use genitive, dative, accusative, and vocative far more than the rest:

enum Case: string {
    case Nominative = 'nominative';
    case Genitive   = 'genitive';   // Jono / Rasos
    case Dative     = 'dative';     // Jonui / Rasai
    case Accusative = 'accusative'; // Joną / Rasą
    case Instrumental = 'instrumental';
    case Locative   = 'locative';
    case Vocative   = 'vocative';   // Jonai / Rasa
}

Decline first name and last name separately. Gender drives the suffix rules and surname endings (-as/-is/-us/-ys male vs -a/-ė/-ienė/-aitė female), so a library that receives one concatenated string has to re-split it and will guess wrong on hyphenated or multi-token names. Pass components and a resolved gender when the API allows it; infer from the surname ending only as a fallback.

Cache aggressively. Declension is a pure function of (first, last, gender, case). A Cache::remember keyed on a hash of those four is free money — invoice generation loops over the same customer names constantly.

Blade integration. A small directive keeps templates clean:

Blade::directive('decline', fn ($expr) => "<?php echo app(NameDeclension::class)->blade($expr); ?>");

Sveiki, @decline($user->first_name, 'vocative')!

Fail soft, always. If the library throws or returns something implausible, log it and return the nominative input. A slightly wrong case in an email is a cosmetic bug; a blank name is a broken email.

Gotchas and Tips

• The bundle is dead weight. Do not register it in a Laravel app, do not add it to config/app.php providers as if it were a package. It targets Symfony 2's DI container. Use the class, discard the bundle. If composer.json constrains php: >=5.3 and nothing else, expect PHP 8 deprecation noise (${var} interpolation, dynamic properties, implicit nullable params) — you're forking anyway.
• Diacritic restoration on the stem is where these libraries break. Lithuanian declension must reintroduce nasal vowels that were lost in the nominative: ą, ę, į, ų. A library that only appends suffixes will produce Jonui correctly but mangle Kazys → Kazio or Ąžuolas forms. Build a test corpus before you trust it: Tomas, Rasa, Giedrius, Kazys, Audronė, Vytautas, Šarūnas, Aušra, Žygimantas, Mantas, Ieva. Assert the full 7-case table for each by hand against a native speaker or authoritative source. This is a half-day of work and it is the whole assessment.
• Encoding. Lithuanian uses ą č ę ė į š ų ū ž. Use mb_* everywhere; never strtolower/ucfirst. Ensure the DB column collation is utf8mb4. Most declension bugs reported by users are actually mojibake upstream of the decliner.
• Vocative is the highest-value and most error-prone case. Male -as names take -ai (Jonas → Jonai) but consonant-stem and -is names behave differently (Giedrius → Giedriau, Kazys → Kazy). Test it explicitly; it's the one your emails actually use.
• Foreign and non-declinable names exist. -ė-ending foreign names, names ending in -o, -i, -u, and particles like van, de, von should pass through unchanged or decline only the last token. Add a passthrough whitelist/pattern and default to nominative rather than guessing.
• Hyphenated surnames (Jonaitis-Brazauskas) need per-token handling. If the library takes a single string it will produce garbage; split on -, decline each part, rejoin.
• No test suite, no maintainer, no issue triage. Read the declension class line by line before shipping. It's probably 100–300 lines of suffix tables — small enough to fully audit, and you'll learn the exact edge cases it doesn't handle.
• Swap-in point. Because you wrapped it, replacing it later is a one-file change. Keep an eye on Packagist for maintained Lithuanian declension libraries and for forks of this repo; the domain is small enough that a hand-written suffix table matched to your actual customer names is a legitimate fallback.