Add getFullNameWithNickname() for old-style nickname display

Webtrees ≤ 1.x rendered '1 NAME Martin /White/' + '2 NICK Chalky' as
'Martin "Chalky" White' by injecting the nickname between given
names and surname. Webtrees 2.x dropped that automatic injection,
so chart modules built on this base only show 'Martin White' even
when a NICK is present in the GEDCOM.

Add an opt-in NameProcessor method that reads the NICK attribute
from the primary NAME fact and reproduces the old-style display
without modifying the GEDCOM. Idempotent when the nickname is
already inline. Chart consumers can call this instead of getFullName()
when their tree owner wants the legacy display back, see issue
magicsunday/webtrees-descendants-chart#79.

Author: magicsunday

src/Processor/NameProcessor.php

@@ -182,6 +182,83 @@ public function getFullName(): string
         return $this->replacePlaceholders($this->primaryName[self::FULL_NAME_WITH_PLACEHOLDERS]);
     }
 
+    /**
+     * Returns the GEDCOM `2 NICK` value of the individual's primary NAME fact, or
+     * an empty string when no nickname is set. The lookup walks all NAME facts and
+     * returns the first NICK it finds.
+     *
+     * @return string
+     */
+    public function getNickname(): string
+    {
+        foreach ($this->individual->facts(['NAME']) as $nameFact) {
+            $nick = $nameFact->attribute('NICK');
+
+            if ($nick !== '') {
+                return $nick;
+            }
+        }
+
+        return '';
+    }
+
+    /**
+     * Returns the full name with the nickname injected in quotes between the given
+     * names and the surname (e.g. `Martin "Chalky" White`). When the GEDCOM has no
+     * NICK, or when the displayed name already contains the nickname inline, the
+     * unmodified full name is returned.
+     *
+     * Mirrors the legacy webtrees ≤ 1.x behaviour and the `BertKoor/wt-module-old-nicknames`
+     * data-fix output, but operates at display time without modifying the GEDCOM.
+     *
+     * @return string
+     */
+    public function getFullNameWithNickname(): string
+    {
+        $nick = $this->getNickname();
+
+        if ($nick === '') {
+            return $this->getFullName();
+        }
+
+        return $this->injectNickname(
+            $this->getFullName(),
+            implode(' ', $this->getLastNames()),
+            $nick
+        );
+    }
+
+    /**
+     * Inserts the quoted nickname before the surname in a flat name string.
+     * Idempotent: if the nickname is already present in quotes, the input is
+     * returned unchanged.
+     *
+     * @param string $fullName Plain full name (e.g. "Martin White")
+     * @param string $surname  Surname tokens joined by spaces (e.g. "White" or "Van Der Berg")
+     * @param string $nick     Nickname without quotes (e.g. "Chalky")
+     *
+     * @return string
+     */
+    private function injectNickname(string $fullName, string $surname, string $nick): string
+    {
+        if ($nick === '' || str_contains($fullName, '"' . $nick . '"')) {
+            return $fullName;
+        }
+
+        $position = ($surname !== '') ? strrpos($fullName, $surname) : false;
+
+        if ($position !== false) {
+            return substr_replace(
+                $fullName,
+                '"' . $nick . '" ' . $surname,
+                $position,
+                strlen($surname)
+            );
+        }
+
+        return $fullName . ' "' . $nick . '"';
+    }
+
     /**
      * Splits a name into an array, removing all name placeholders.
      *

tests/NameProcessorTest.php

@@ -384,4 +384,49 @@ public function getMarriedSurnamesReturnsEmptyWhenSpouseSurnameDoesNotMatchAnyMa
             $spouseStub
         ));
     }
+
+    /**
+     * @return array<string, array{string, string, string, string}>
+     */
+    public static function injectNicknameDataProvider(): array
+    {
+        // [ fullName, surname, nick, expected ]
+        return [
+            'Empty nick returns input unchanged' => [
+                'Martin White', 'White', '', 'Martin White',
+            ],
+            'Inserts before single-word surname' => [
+                'Martin White', 'White', 'Chalky', 'Martin "Chalky" White',
+            ],
+            'Inserts before multi-word surname' => [
+                'Hans Van Der Berg', 'Van Der Berg', 'Hänschen', 'Hans "Hänschen" Van Der Berg',
+            ],
+            'Idempotent: nick already inline' => [
+                'Martin "Chalky" White', 'White', 'Chalky', 'Martin "Chalky" White',
+            ],
+            'No surname found: appends nick' => [
+                'Anonymous', 'White', 'Chalky', 'Anonymous "Chalky"',
+            ],
+            'Empty surname: appends nick' => [
+                'Anonymous', '', 'Chalky', 'Anonymous "Chalky"',
+            ],
+            'Hits last occurrence when surname is also a given name' => [
+                'White Robert White', 'White', 'Bob', 'White Robert "Bob" White',
+            ],
+        ];
+    }
+
+    /**
+     * @throws ReflectionException
+     */
+    #[Test]
+    #[DataProvider('injectNicknameDataProvider')]
+    public function injectNickname(string $fullName, string $surname, string $nick, string $expected): void
+    {
+        $processorStub    = self::createStub(NameProcessor::class);
+        $reflectionMethod = (new ReflectionClass(NameProcessor::class))->getMethod('injectNickname');
+        $result           = $reflectionMethod->invoke($processorStub, $fullName, $surname, $nick);
+
+        self::assertSame($expected, $result);
+    }
 }