feat(phone-parser): normalize RU phones and extract first candidate

includes/class-phone-parser.php

@@ -0,0 +1,72 @@
+<?php
+declare(strict_types=1);
+
+namespace Cf7stg;
+
+final class PhoneParser
+{
+    /**
+     * Extract and normalize the first phone number from arbitrary text.
+     *
+     * @return array{e164:string,pretty:string,is_russian:bool}|null
+     */
+    public static function parse(string $text): ?array
+    {
+        $text = (string)$text;
+        if ($text === '') {
+            return null;
+        }
+
+        // Find a run of digits, spaces, dashes, parens, dots and a leading '+',
+        // with at least 10 digits in total. Walk candidates left-to-right and
+        // pick the first that yields 10 or 11 digits.
+        if (!preg_match_all('/\+?[\d][\d\s().\-]{8,}/u', $text, $m)) {
+            return null;
+        }
+
+        foreach ($m[0] as $candidate) {
+            $digits = preg_replace('/\D+/', '', $candidate) ?? '';
+            $plus = strpos($candidate, '+') === 0;
+
+            // Russian detection & normalization
+            if (!$plus && strlen($digits) === 11 && $digits[0] === '8') {
+                $digits = '7' . substr($digits, 1);
+            }
+            if (!$plus && strlen($digits) === 10 && preg_match('/^[3-9]/', $digits)) {
+                // Bare 10-digit RU mobile/landline area code
+                $digits = '7' . $digits;
+            }
+
+            if (strlen($digits) < 10 || strlen($digits) > 15) {
+                continue;
+            }
+
+            $e164 = '+' . $digits;
+            $is_ru = (strlen($digits) === 11 && $digits[0] === '7');
+
+            return [
+                'e164'       => $e164,
+                'pretty'     => self::format_pretty($e164, $is_ru),
+                'is_russian' => $is_ru,
+            ];
+        }
+
+        return null;
+    }
+
+    private static function format_pretty(string $e164, bool $is_ru): string
+    {
+        if ($is_ru) {
+            // +7 XXX XXX-XX-XX → "+7 (XXX) XXX-XX-XX"
+            $d = substr($e164, 2);
+            return sprintf(
+                '+7 (%s) %s-%s-%s',
+                substr($d, 0, 3),
+                substr($d, 3, 3),
+                substr($d, 6, 2),
+                substr($d, 8, 2)
+            );
+        }
+        return $e164;
+    }
+}

tests/PhoneParserTest.php

@@ -0,0 +1,75 @@
+<?php
+declare(strict_types=1);
+
+namespace Cf7stg\Tests;
+
+use Cf7stg\PhoneParser;
+use PHPUnit\Framework\TestCase;
+
+final class PhoneParserTest extends TestCase
+{
+    public function test_ru_plus7_formatted(): void
+    {
+        $r = PhoneParser::parse('+7 (903) 123-45-67');
+        self::assertSame('+79031234567', $r['e164']);
+        self::assertSame('+7 (903) 123-45-67', $r['pretty']);
+        self::assertTrue($r['is_russian']);
+    }
+
+    public function test_ru_leading_eight(): void
+    {
+        $r = PhoneParser::parse('89031234567');
+        self::assertSame('+79031234567', $r['e164']);
+        self::assertSame('+7 (903) 123-45-67', $r['pretty']);
+        self::assertTrue($r['is_russian']);
+    }
+
+    public function test_ru_bare_ten_digits(): void
+    {
+        $r = PhoneParser::parse('9031234567');
+        self::assertSame('+79031234567', $r['e164']);
+        self::assertTrue($r['is_russian']);
+    }
+
+    public function test_foreign_us_number(): void
+    {
+        $r = PhoneParser::parse('+1 555 123 4567');
+        self::assertSame('+15551234567', $r['e164']);
+        self::assertFalse($r['is_russian']);
+    }
+
+    public function test_embedded_in_text(): void
+    {
+        $r = PhoneParser::parse('Позвоните мне: +7-903-123-45-67, после 18:00');
+        self::assertSame('+79031234567', $r['e164']);
+        self::assertTrue($r['is_russian']);
+    }
+
+    public function test_returns_first_of_multiple(): void
+    {
+        $r = PhoneParser::parse('Домашний 84951234567, мобильный 89031234567');
+        self::assertSame('+74951234567', $r['e164']);
+    }
+
+    public function test_garbage_returns_null(): void
+    {
+        self::assertNull(PhoneParser::parse('позвоните!!!'));
+    }
+
+    public function test_empty_returns_null(): void
+    {
+        self::assertNull(PhoneParser::parse(''));
+    }
+
+    public function test_too_short_returns_null(): void
+    {
+        self::assertNull(PhoneParser::parse('12345'));
+    }
+
+    public function test_ru_moscow_landline(): void
+    {
+        $r = PhoneParser::parse('+7 (495) 123-45-67');
+        self::assertSame('+74951234567', $r['e164']);
+        self::assertTrue($r['is_russian']);
+    }
+}