README

Converts Czech names from nominative (1st case) to vocative (5th case) so you can address people properly — and detects gender from a name along the way.

use ReinertTomas\CzechVocative\CzechName;

CzechName::of('Petr')->vocative();     // 'Petře'
CzechName::of('Novák')->vocative();    // 'Nováku'
CzechName::of('Adriana')->vocative();  // 'Adriano'

Installation

composer require reinerttomas/czech-vocative

Requires PHP 8.2+ with ext-mbstring. No runtime dependencies.

Usage

CzechName::of() validates and normalizes the input (trims it, converts to title case) and throws InvalidNameException for an empty string or a name ending with a non-letter.

use ReinertTomas\CzechVocative\CzechName;
use ReinertTomas\CzechVocative\Gender;

$name = CzechName::of('  petr ');

$name->nominative();  // 'Petr'
$name->vocative();    // 'Petře'
$name->gender();      // Gender::Male
(string) $name;       // 'Petr'

Gender and first-name/surname detection is automatic, but you can pass explicit hints (the surname hint only affects female names — female surnames stay unchanged in vocative):

CzechName::of('Nováková', gender: Gender::Female, isSurname: true)->vocative();
// 'Nováková'

CzechName::of('Petra', isSurname: false)->vocative();
// 'Petro'

Full names ("Petr Novák") are intentionally not supported — split the name yourself and inflect the parts, since deciding what is a surname is ambiguous.

How it works

The library matches the name's suffix against rule tables (longest suffix wins) and replaces it with the vocative ending. Male names are inflected via ~350 suffix rules, female first names change a trailing -a to -o, female surnames stay unchanged. Gender detection uses ~700 suffix rules with a claimed accuracy of 99.7 %.

This library is inspired by granam/czech-vocative, a PHP port of the same algorithm. It is a fresh implementation with a modern API and takes its data directly from the original source instead.

The rule tables come from the Python library Mimino666/vokativ (MIT license) and are derived from Czech Statistical Office name frequency statistics. They are committed to this repository as plain PHP arrays; bin/import-data.sh regenerates them (requires python3 and curl). The upstream test data is imported too — the test suite verifies parity with the original on all 400 fixture names.

Development

composer test     # Pest
composer phpstan  # PHPStan (level max)
composer lint     # Pint --test

License

MIT. Data and algorithm adapted from Mimino666/vokativ by Michal Mimino Danilak (MIT).

reinerttomas / czech-vocative

Maintainers

Package info

Statistics

Security