3.0.0

Breaking changes

• PlaceProcessor::__construct() now takes (Individual $individual, PlaceFormatSpec $format, IsoCountryMap $countryMap). Place shortening is no longer configured through loose parameters; a consumer resolves its own settings into a PlaceFormatSpec value object once and hands that in, together with the country resolver. Consumers that construct a PlaceProcessor directly must adapt; nothing else in the public API changed.

• New runtime requirements: ext-intl and ext-mbstring. The country resolver is built on ICU (Locale::getDisplayRegion) and folds its display names with mbstring. Both are declared in composer.json, so an installation without them is rejected during resolution instead of failing at runtime.

New

• Support\Locale\IsoCountryMap — resolves free-text country names from GEDCOM PLAC lines to ISO-3166-1 alpha-2 codes (Germany/Deutschland → DE), converts alpha-2 to alpha-3 through ICU's supplemental codeMappings table (DE → DEU), and renders localised country labels. Nine widely used locales are pre-seeded alongside the active webtrees locale, with the reverse lookup memoised so repeat queries stay O(1). Common informal spellings and abbreviations (USA, UK, Great Britain, the UK home nations) are carried as explicit aliases. Shared here so the chart modules stop re-deriving it.

• A typed place-format model — Model\PlaceStyle (the axis a name is shortened along), Model\PlaceFormatSpec (a final readonly value object carrying the resolved parameters, rejecting an invalid level count at construction) and Model\PlaceFormatChoice (a backed enum mapping a stored preference onto a spec, including an "automatic" source that reads the tree's own settings).

• Five place-shortening styles in PlaceProcessor — Full (as recorded), Levels (keep N hierarchy levels from either end), CityCountry (keep the locality and the country, spelling a three-letter country code out in the interface language), plus CityIso2 and CityIso3, which render the country as its ISO-3166-1 alpha-2 or alpha-3 code.

Notes on the place-code behaviour

• Only three-letter country codes are expanded. A bare two-letter segment is kept verbatim, because those collide with US and German state abbreviations — Dover, DE is Delaware and Ulm, BW is Baden-Württemberg, not Germany and Botswana.

• For a place recorded as a single segment, the ISO styles read it as the country, except when its resolved code is one of a small curated set of countries whose name is also a well-known city (Luxembourg, Monaco, …), where the recorded text is kept. A lone alpha-3 code still resolves, since a code is never a city name.

• Every resolution failure degrades to the recorded text. A place is never dropped or mangled.

Upgrading from 2.x

Consumers pin ^2.x and are not moved by this release; adopt it when convenient. Where a PlaceProcessor is constructed directly, resolve the desired formatting into a spec first:

// The tree's own settings are always passed; every choice except Automatic
// is already fully determined and ignores them.
$spec = PlaceFormatChoice::CityCountry->toSpec($treeLevels, $treeSuffix);

$processor = new PlaceProcessor($individual, $spec, new IsoCountryMap());

PlaceFormatChoice::Automatic->toSpec($treeLevels, $treeSuffix) reproduces the previous tree-driven behaviour. IsoCountryMap takes an optional locale; left empty it follows the active webtrees locale.