Person names

A ContactCard keeps a person's name as one text, name, and may also keep it in its parts, structuredName, a PersonName. The parts let the name be written and sorted as its culture does: Charles de Gaulle sorts under Gaulle in French, Herman Van Rompuy under Van Rompuy in the Dutch of Belgium, and Bartók Béla is written family name first in Hungarian.

$name = PersonName::of(given: 'Charles', family: 'Gaulle', particle: 'de', culture: 'fr');

$name->display();   // "Charles de Gaulle"
$name->sortKey();   // "Gaulle, Charles de"

$card = ContactCard::of(structuredName: $name);
$card->name;        // "Charles de Gaulle"

The parts

PersonName::of() trims each text; an empty one is none. A name has a given name or a family name, each part is 255 characters or fewer and holds no control character, and a language tag has a language of two or three letters and parts of one to eight letters or digits after it, 35 characters in all. InvalidContact is thrown otherwise. On a card, the display form of the name is the card's name when the card is given none, and it is 255 characters or fewer too.

Writing and sorting

Given name first, display() writes the given name, the additional names and the family name; family name first, the family name, the additional names and the given name, as Vietnamese writes Võ Nguyên Giáp. Chinese, Japanese and Korean names written in their own characters are joined without a space, 毛泽东, and with one when romanised, Mao Zedong.

sortKey() puts the sorted family name first, then the given and additional names, then what the sort leaves out of the particle: Gogh, Vincent van. What the key keeps of a particle starts with a capital, as a sorted list prints it: Du Bellay, Joachim. A culture that sorts by the given name puts it first: Giáp, Võ Nguyên. Sort the keys with a collator of the reader's language, Collator::compare() of ext-intl: the key orders the parts, the collator orders the letters.

Each method takes a NameConvention as an optional argument, which wins over the name's culture.

The conventions of the library

NameConventions::for($culture) gives the convention of a culture, by its language and, for Dutch, its country:

A name without a culture follows the last row. An application that knows a culture better builds its own NameConvention — its order, the leading words of a particle dropped from the sort key, whether the whole particle is dropped, whether names sort by the given name, whether names in Chinese, Japanese or Korean characters are joined — and gives it to the methods.

In the other formats