amare/app/Domain/Contact/BrazilianPhoneNumber.php

<?php

declare(strict_types=1);

namespace App\Domain\Contact;

/**
 * Normalizes a raw phone/WhatsApp number typed into the public briefing
 * form into a canonical, human-readable Brazilian format.
 *
 * The briefing e-mail simply prints the field value in a table, so the
 * canonical form must stay legible for the staff member reading it —
 * "(11) 98888-7777" rather than an opaque "11988887777" digit string.
 */
final class BrazilianPhoneNumber
{
    /**
     * Formats to "(DD) 9XXXX-XXXX" for an 11-digit mobile number or
     * "(DD) XXXX-XXXX" for a 10-digit landline number, stripping a
     * leading "+55"/"55" country code when present.
     *
     * A 10- or 11-digit string is only formatted when it is structurally
     * plausible as a Brazilian number: the first two digits must be a
     * possible DDD (`[1-9][1-9]`, since Brazilian area codes run 11-99
     * and never carry a '0' in either position), and an 11-digit number
     * must additionally have a '9' as its third digit (mandatory on all
     * Brazilian mobile numbers since 2012). An explicit "+55" prefix that
     * leaves no digits for a DDD (e.g. "+55 98888-7777") is treated as a
     * number missing its area code, not as DDD 55.
     *
     * When the digit count does not match either shape, or the shape
     * fails the checks above (foreign numbers, partial input, extensions,
     * etc.), the original text is preserved — only whitespace is
     * collapsed — so no information the recipient might need is
     * discarded or silently fabricated.
     */
    public static function normalize(string $raw): string
    {
        $trimmed = trim($raw);
        $collapsed = preg_replace('/\s+/', ' ', $trimmed) ?? $trimmed;

        // Only reformat when the text is made exclusively of phone
        // characters. Anything else — "(WhatsApp)", "falar com João",
        // a ramal — is information the recipient needs, so it is left
        // untouched rather than stripped away by the digit extraction.
        if (preg_match('/^[0-9()+\-.\/ ]+$/', $collapsed) !== 1) {
            return $collapsed;
        }

        $digits = preg_replace('/\D+/', '', $collapsed) ?? '';

        if (in_array(strlen($digits), [12, 13], true) && str_starts_with($digits, '55')) {
            $digits = substr($digits, 2);
        } elseif (str_starts_with($digits, '55') && preg_match('/^\+\s*55\b/', $collapsed) === 1) {
            // An explicit "+55" was written, but the total digit count
            // never reached 12/13, meaning nothing precedes it that could
            // be a DDD — e.g. "+55 98888-7777" is a mobile number missing
            // its area code, not DDD 55 with a coincidentally-matching
            // subscriber number. Guessing a DDD here would fabricate one.
            return $collapsed;
        }

        return match (strlen($digits)) {
            11 => self::isPlausibleDdd($digits) && $digits[2] === '9'
                ? sprintf('(%s) %s-%s', substr($digits, 0, 2), substr($digits, 2, 5), substr($digits, 7))
                : $collapsed,
            10 => self::isPlausibleDdd($digits)
                ? sprintf('(%s) %s-%s', substr($digits, 0, 2), substr($digits, 2, 4), substr($digits, 6))
                : $collapsed,
            default => $collapsed,
        };
    }

    /**
     * A Brazilian DDD (area code) runs 11-99: the first digit is never
     * '0' (not a valid leading digit) and the second is never '0' either
     * (no DDD like "10", "20", "30" exists). This does not check that the
     * DDD is one of the officially assigned codes — only that its shape
     * is plausible enough to distinguish it from a foreign number.
     */
    private static function isPlausibleDdd(string $digits): bool
    {
        return preg_match('/^[1-9][1-9]/', $digits) === 1;
    }
}