Proyectos de Subversion Moodle

<?php

declare(strict_types=1);

namespace libphonenumber;

/**

 * Utility for international phone numbers. Functionality includes formatting, parsing and

 * validation.

 *

 * <p>If you use this library, and want to be notified about important changes, please sign up to

 * our <a href="http://groups.google.com/group/libphonenumber-discuss/about">mailing list</a>.

 *

 * NOTE: A lot of methods in this class require Region Code strings. These must be provided using

 * CLDR two-letter region-code format. These should be in upper-case. The list of the codes

 * can be found here:

 * http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html

 * @phpstan-consistent-constructor

 */

class PhoneNumberUtil

{

    /** Flags to use when compiling regular expressions for phone numbers */

    protected const REGEX_FLAGS = 'ui'; //Unicode and case insensitive

    // The minimum and maximum length of the national significant number.

    protected const MIN_LENGTH_FOR_NSN = 2;

    // The ITU says the maximum length should be 15, but we have found longer numbers in Germany.

    protected const MAX_LENGTH_FOR_NSN = 17;

    // We don't allow input strings for parsing to be longer than 250 chars. This prevents malicious

    // input from overflowing the regular-expression engine.

    protected const MAX_INPUT_STRING_LENGTH = 250;

    // The maximum length of the country calling code.

    protected const MAX_LENGTH_COUNTRY_CODE = 3;

    /**

     * @internal

     */

    public const REGION_CODE_FOR_NON_GEO_ENTITY = '001';

    /**

     * @internal

     */

    public const META_DATA_FILE_PREFIX = __DIR__ . '/data/PhoneNumberMetadata';

    // Region-code for the unknown region.

    protected const UNKNOWN_REGION = 'ZZ';

    protected const NANPA_COUNTRY_CODE = 1;

    // The PLUS_SIGN signifies the international prefix.

    protected const PLUS_SIGN = '+';

    protected const PLUS_CHARS = '+＋';

    protected const STAR_SIGN = '*';

    protected const RFC3966_EXTN_PREFIX = ';ext=';

    protected const RFC3966_PREFIX = 'tel:';

    protected const RFC3966_PHONE_CONTEXT = ';phone-context=';

    protected const RFC3966_ISDN_SUBADDRESS = ';isub=';

    // We use this pattern to check if the phone number has at least three letters in it - if so, then

    // we treat it as a number where some phone-number digits are represented by letters.

    protected const VALID_ALPHA_PHONE_PATTERN = '(?:.*?[A-Za-z]){3}.*';

    // We accept alpha characters in phone numbers, ASCII only, upper and lower case.

    protected const VALID_ALPHA = 'A-Za-z';

    // Default extension prefix to use when formatting. This will be put in front of any extension

    // component of the number, after the main national number is formatted. For example, if you wish

    // the default extension formatting to be " extn: 3456", then you should specify " extn: " here

    // as the default extension prefix. This can be overridden by region-specific preferences.

    protected const DEFAULT_EXTN_PREFIX = ' ext. ';

    // Regular expression of acceptable punctuation found in phone numbers, used to find numbers in

    // text and to decide what is a viable phone number. This excludes diallable characters.

    // This consists of dash characters, white space characters, full stops, slashes,

    // square brackets, parentheses and tildes. It also includes the letter 'x' as that is found as a

    // placeholder for carrier information in some phone numbers. Full-width variants are also

    // present.

    protected const VALID_PUNCTUATION = "-x\xE2\x80\x90-\xE2\x80\x95\xE2\x88\x92\xE3\x83\xBC\xEF\xBC\x8D-\xEF\xBC\x8F \xC2\xA0\xC2\xAD\xE2\x80\x8B\xE2\x81\xA0\xE3\x80\x80()\xEF\xBC\x88\xEF\xBC\x89\xEF\xBC\xBB\xEF\xBC\xBD.\\[\\]/~\xE2\x81\x93\xE2\x88\xBC";

    protected const DIGITS = '\\p{Nd}';

    // Pattern that makes it easy to distinguish whether a region has a single international dialing

    // prefix or not. If a region has a single international prefix (e.g. 011 in USA), it will be

    // represented as a string that contains a sequence of ASCII digits, and possible a tilde, which

    // signals waiting for the tone. If there are multiple available international prefixes in a

    // region, they will be represented as a regex string that always contains one or more characters

    // that are not ASCII digits or a tilde.

    protected const SINGLE_INTERNATIONAL_PREFIX = "[\\d]+(?:[~\xE2\x81\x93\xE2\x88\xBC\xEF\xBD\x9E][\\d]+)?";

    protected const NON_DIGITS_PATTERN = '(\\D+)';

    // The FIRST_GROUP_PATTERN was originally set to $1 but there are some countries for which the

    // first group is not used in the national pattern (e.g. Argentina) so the $1 group does not match

    // correctly. Therefore, we use \d, so that the first group actually used in the pattern will be

    // matched.

    protected const FIRST_GROUP_PATTERN = '(\$\\d)';

    // Constants used in the formatting rules to represent the national prefix, first group and

    // carrier code respectively.

    protected const NP_STRING = '$NP';

    protected const FG_STRING = '$FG';

    protected const CC_STRING = '$CC';

    // A pattern that is used to determine if the national prefix formatting rule has the first group

    // only, i.e, does not start with the national prefix. Note that the pattern explicitly allows

    // for unbalanced parentheses.

    protected const FIRST_GROUP_ONLY_PREFIX_PATTERN = '\\(?\\$1\\)?';

    /**

     * @internal

     */

    public const PLUS_CHARS_PATTERN = '[' . self::PLUS_CHARS . ']+';

    protected const SEPARATOR_PATTERN = '[' . self::VALID_PUNCTUATION . ']+';

    protected const CAPTURING_DIGIT_PATTERN = '(' . self::DIGITS . ')';

    protected const VALID_START_CHAR_PATTERN = '[' . self::PLUS_CHARS . self::DIGITS . ']';

    protected const SECOND_NUMBER_START_PATTERN = '[\\\\/] *x';

    //protected const UNWANTED_END_CHAR_PATTERN = '[[\\P{N}&&\\P{L}]&&[^#]]+$';

    protected const UNWANTED_END_CHAR_PATTERN = '[^' . self::DIGITS . self::VALID_ALPHA . '#]+$';

    protected const DIALLABLE_CHAR_MAPPINGS = self::ASCII_DIGIT_MAPPINGS

        + [self::PLUS_SIGN => self::PLUS_SIGN]

    + ['*' => '*', '#' => '#'];

    protected static ?PhoneNumberUtil $instance = null;

    /**

     * Only upper-case variants of alpha characters are stored.

     */

    protected const ALPHA_MAPPINGS = [

        'A' => '2',

        'B' => '2',

        'C' => '2',

        'D' => '3',

        'E' => '3',

        'F' => '3',

        'G' => '4',

        'H' => '4',

        'I' => '4',

        'J' => '5',

        'K' => '5',

        'L' => '5',

        'M' => '6',

        'N' => '6',

        'O' => '6',

        'P' => '7',

        'Q' => '7',

        'R' => '7',

        'S' => '7',

        'T' => '8',

        'U' => '8',

        'V' => '8',

        'W' => '9',

        'X' => '9',

        'Y' => '9',

        'Z' => '9',

    ];

    /**

     * Map of country calling codes that use a mobile token before the area code. One example of when

     * this is relevant is when determining the length of the national destination code, which should

     * be the length of the area code plus the length of the mobile token.

     */

    protected const MOBILE_TOKEN_MAPPINGS = [

        '54' => '9',

    ];

    /**

     * Set of country codes that have geographically assigned mobile numbers (see GEO_MOBILE_COUNTRIES

     * below) which are not based on *area codes*. For example, in China mobile numbers start with a

     * carrier indicator, and beyond that are geographically assigned: this carrier indicator is not

     * considered to be an area code.

     */

    protected const GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES = [

        86, // China

    ];

    /**

     * Set of country codes that doesn't have national prefix, but it has area codes.

     */

    protected const COUNTRIES_WITHOUT_NATIONAL_PREFIX_WITH_AREA_CODES = [

        52, // Mexico

    ];

    /**

     * Set of country calling codes that have geographically assigned mobile numbers. This may not be

     * complete; we add calling codes case by case, as we find geographical mobile numbers or hear

     * from user reports. Note that countries like the US, where we can't distinguish between

     * fixed-line or mobile numbers, are not listed here, since we consider FIXED_LINE_OR_MOBILE to be

     * a possibly geographically-related type anyway (like FIXED_LINE).

     */

    protected const GEO_MOBILE_COUNTRIES = [

        52, // Mexico

        54, // Argentina

        55, // Brazil

        62, // Indonesia: some prefixes only (fixed CMDA wireless)

    ] + self::GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES;

    /**

     * For performance reasons, amalgamate both into one map.

     */

    protected const ALPHA_PHONE_MAPPINGS = self::ALPHA_MAPPINGS + self::ASCII_DIGIT_MAPPINGS;

    /**

     * Separate map of all symbols that we wish to retain when formatting alpha numbers. This

     * includes digits, ASCII letters and number grouping symbols such as "-" and " ".

     *

     * @var array<string,string>

     */

    protected static array $ALL_PLUS_NUMBER_GROUPING_SYMBOLS;

    /**

     * Simple ASCII digits map used to populate ALPHA_PHONE_MAPPINGS and

     * ALL_PLUS_NUMBER_GROUPING_SYMBOLS.

     */

    protected const ASCII_DIGIT_MAPPINGS = [

        '0' => '0',

        '1' => '1',

        '2' => '2',

        '3' => '3',

        '4' => '4',

        '5' => '5',

        '6' => '6',

        '7' => '7',

        '8' => '8',

        '9' => '9',

    ];

    /**

     * Regexp of all possible ways to write extensions, for use when parsing. This will be run as a

     * case-insensitive regexp match. Wide character versions are also provided after each ASCII

     * version.

     */

    protected static string $EXTN_PATTERNS_FOR_PARSING;

    protected static string $EXTN_PATTERNS_FOR_MATCHING;

    // Regular expression of valid global-number-digits for the phone-context parameter, following the

    // syntax defined in RFC3966.

    protected static string $RFC3966_VISUAL_SEPARATOR = '[\\-\\.\\(\\)]?';

    protected static string $RFC3966_PHONE_DIGIT;

    protected static string $RFC3966_GLOBAL_NUMBER_DIGITS;

    // Regular expression of valid domainname for the phone-context parameter, following the syntax

    // defined in RFC3966.

    protected static string $ALPHANUM;

    protected static string $RFC3966_DOMAINLABEL;

    protected static string $RFC3966_TOPLABEL;

    protected static string $RFC3966_DOMAINNAME;

    protected static string $EXTN_PATTERN;

    protected static string $VALID_PHONE_NUMBER_PATTERN;

    protected static string $MIN_LENGTH_PHONE_NUMBER_PATTERN;

    /**

     *  Regular expression of viable phone numbers. This is location independent. Checks we have at

     * least three leading digits, and only valid punctuation, alpha characters and

     * digits in the phone number. Does not include extension data.

     * The symbol 'x' is allowed here as valid punctuation since it is often used as a placeholder for

     * carrier codes, for example in Brazilian phone numbers. We also allow multiple "+" characters at

     * the start.

     * Corresponds to the following:

     * [digits]{minLengthNsn}|

     * plus_sign*(([punctuation]|[star])*[digits]){3,}([punctuation]|[star]|[digits]|[alpha])*

     *

     * The first reg-ex is to allow short numbers (two digits long) to be parsed if they are entered

     * as "15" etc, but only if there is no punctuation in them. The second expression restricts the

     * number of digits to three or more, but then allows them to be in international form, and to

     * have alpha-characters and punctuation.

     *

     * Note VALID_PUNCTUATION starts with a -, so must be the first in the range.

     */

    protected static string $VALID_PHONE_NUMBER;

    /**

     * @var array<string,int>

     */

    protected const NUMERIC_CHARACTERS = [

        "\xef\xbc\x90" => 0,

        "\xef\xbc\x91" => 1,

        "\xef\xbc\x92" => 2,

        "\xef\xbc\x93" => 3,

        "\xef\xbc\x94" => 4,

        "\xef\xbc\x95" => 5,

        "\xef\xbc\x96" => 6,

        "\xef\xbc\x97" => 7,

        "\xef\xbc\x98" => 8,

        "\xef\xbc\x99" => 9,

        "\xd9\xa0" => 0,

        "\xd9\xa1" => 1,

        "\xd9\xa2" => 2,

        "\xd9\xa3" => 3,

        "\xd9\xa4" => 4,

        "\xd9\xa5" => 5,

        "\xd9\xa6" => 6,

        "\xd9\xa7" => 7,

        "\xd9\xa8" => 8,

        "\xd9\xa9" => 9,

        "\xdb\xb0" => 0,

        "\xdb\xb1" => 1,

        "\xdb\xb2" => 2,

        "\xdb\xb3" => 3,

        "\xdb\xb4" => 4,

        "\xdb\xb5" => 5,

        "\xdb\xb6" => 6,

        "\xdb\xb7" => 7,

        "\xdb\xb8" => 8,

        "\xdb\xb9" => 9,

        "\xe1\xa0\x90" => 0,

        "\xe1\xa0\x91" => 1,

        "\xe1\xa0\x92" => 2,

        "\xe1\xa0\x93" => 3,

        "\xe1\xa0\x94" => 4,

        "\xe1\xa0\x95" => 5,

        "\xe1\xa0\x96" => 6,

        "\xe1\xa0\x97" => 7,

        "\xe1\xa0\x98" => 8,

        "\xe1\xa0\x99" => 9,

    ];

    /**

     * The set of county calling codes that map to the non-geo entity region ("001").

     *

     * @var int[]

     */

    protected array $countryCodesForNonGeographicalRegion = [];

    /**

     * The set of regions the library supports.

     *

     * @var string[]

     */

    protected array $supportedRegions = [];

    /**

     * A mapping from a country calling code to the region codes which denote the region represented

     * by that country calling code. In the case of multiple regions sharing a calling code, such as

     * the NANPA regions, the one indicated with "isMainCountryForCode" in the metadata should be

     * first.

     *

     * @var array<int,string[]>

     */

    protected array $countryCallingCodeToRegionCodeMap = [];

    /**

     * The set of regions that share country calling code 1.

     *

     * @var string[]

     */

    protected array $nanpaRegions = [];

    protected MetadataSourceInterface $metadataSource;

    protected MatcherAPIInterface $matcherAPI;

    /**

     * This class implements a singleton, so the only constructor is protected.

     * @param array<int,string[]> $countryCallingCodeToRegionCodeMap

     */

    protected function __construct(MetadataSourceInterface $metadataSource, array $countryCallingCodeToRegionCodeMap)

    {

        $this->metadataSource = $metadataSource;

        $this->countryCallingCodeToRegionCodeMap = $countryCallingCodeToRegionCodeMap;

        $this->init();

        $this->matcherAPI = RegexBasedMatcher::create();

        static::initExtnPatterns();

        static::initExtnPattern();

        static::initRFC3966Patterns();

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS = [];

        // Put (lower letter -> upper letter) and (upper letter -> upper letter) mappings.

        foreach (static::ALPHA_MAPPINGS as $c => $value) {

            static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS[strtolower($c)] = $c;

            static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS[(string) $c] = (string) $c;

        }

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS += static::ASCII_DIGIT_MAPPINGS;

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS['-'] = '-';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xEF\xBC\x8D"] = '-';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x90"] = '-';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x91"] = '-';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x92"] = '-';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x93"] = '-';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x94"] = '-';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x95"] = '-';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x88\x92"] = '-';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS['/'] = '/';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xEF\xBC\x8F"] = '/';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS[' '] = ' ';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE3\x80\x80"] = ' ';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x81\xA0"] = ' ';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS['.'] = '.';

        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xEF\xBC\x8E"] = '.';

        static::initValidPhoneNumberPatterns();

    }

    /**

     * Gets a {@link PhoneNumberUtil} instance to carry out international phone number formatting,

     * parsing or validation. The instance is loaded with phone number metadata for a number of most

     * commonly used regions.

     *

     * <p>The {@link PhoneNumberUtil} is implemented as a singleton. Therefore, calling getInstance

     * multiple times will only result in one instance being created.

     *

     * @param array<int,array<int|string>>|null $countryCallingCodeToRegionCodeMap

     * @return PhoneNumberUtil instance

     */

    public static function getInstance(

        string $baseFileLocation = self::META_DATA_FILE_PREFIX,

        ?array $countryCallingCodeToRegionCodeMap = null,

        ?MetadataLoaderInterface $metadataLoader = null,

        ?MetadataSourceInterface $metadataSource = null

    ): PhoneNumberUtil {

        if (static::$instance === null) {

            if ($countryCallingCodeToRegionCodeMap === null) {

                $countryCallingCodeToRegionCodeMap = CountryCodeToRegionCodeMap::COUNTRY_CODE_TO_REGION_CODE_MAP;

            }

            if ($metadataLoader === null) {

                $metadataLoader = new DefaultMetadataLoader();

            }

            if ($metadataSource === null) {

                $metadataSource = new MultiFileMetadataSourceImpl($metadataLoader, $baseFileLocation);

            }

            static::$instance = new static($metadataSource, $countryCallingCodeToRegionCodeMap);

        }

        return static::$instance;

    }

    protected function init(): void

    {

        $supportedRegions = [[]];

        foreach ($this->countryCallingCodeToRegionCodeMap as $countryCode => $regionCodes) {

            // We can assume that if the country calling code maps to the non-geo entity region code then

            // that's the only region code it maps to.

            if (count($regionCodes) === 1 && static::REGION_CODE_FOR_NON_GEO_ENTITY === $regionCodes[0]) {

                // This is the subset of all country codes that map to the non-geo entity region code.

                $this->countryCodesForNonGeographicalRegion[] = $countryCode;

            } else {

                // The supported regions set does not include the "001" non-geo entity region code.

                $supportedRegions[] = $regionCodes;

            }

        }

        $this->supportedRegions = array_merge(...$supportedRegions);

        // If the non-geo entity still got added to the set of supported regions it must be because

        // there are entries that list the non-geo entity alongside normal regions (which is wrong).

        // If we discover this, remove the non-geo entity from the set of supported regions and log.

        $idx_region_code_non_geo_entity = array_search(static::REGION_CODE_FOR_NON_GEO_ENTITY, $this->supportedRegions);

        if ($idx_region_code_non_geo_entity !== false) {

            unset($this->supportedRegions[$idx_region_code_non_geo_entity]);

        }

        $this->nanpaRegions = $this->countryCallingCodeToRegionCodeMap[static::NANPA_COUNTRY_CODE];

    }

    protected static function initExtnPatterns(): void

    {

        static::$EXTN_PATTERNS_FOR_PARSING = static::createExtnPattern(true);

        static::$EXTN_PATTERNS_FOR_MATCHING = static::createExtnPattern(false);

    }

    protected static function initRFC3966Patterns(): void

    {

        static::$RFC3966_PHONE_DIGIT = '(' . static::DIGITS . '|' . static::$RFC3966_VISUAL_SEPARATOR . ')';

        static::$RFC3966_GLOBAL_NUMBER_DIGITS = '^\\' . static::PLUS_SIGN . static::$RFC3966_PHONE_DIGIT . '*' . static::DIGITS . static::$RFC3966_PHONE_DIGIT . '*$';

        static::$ALPHANUM = static::VALID_ALPHA . static::DIGITS;

        static::$RFC3966_DOMAINLABEL = '[' . static::$ALPHANUM . ']+((\\-)*[' . static::$ALPHANUM . '])*';

        static::$RFC3966_TOPLABEL = '[' . static::VALID_ALPHA . ']+((\\-)*[' . static::$ALPHANUM . '])*';

        static::$RFC3966_DOMAINNAME = '^(' . static::$RFC3966_DOMAINLABEL . '\\.)*' . static::$RFC3966_TOPLABEL . '\\.?$';

    }

    /**

     * Helper method for constructing regular expressions for parsing. Creates an expression that

     * captures up to maxLength digits.

     */

    protected static function extnDigits(int $maxLength): string

    {

        return '(' . self::DIGITS . '{1,' . $maxLength . '})';

    }

    /**

     * Helper initialiser method to create the regular-expression pattern to match extensions.

     * Note that there are currently six capturing groups for the extension itself. If this number is

     * changed, MaybeStripExtension needs to be updated.

     */

    protected static function createExtnPattern(bool $forParsing): string

    {

        // We cap the maximum length of an extension based on the ambiguity of the way the extension is

        // prefixed. As per ITU, the officially allowed length for extensions is actually 40, but we

        // don't support this since we haven't seen real examples and this introduces many false

        // interpretations as the extension labels are not standardized.

        $extLimitAfterExplicitLabel = 20;

        $extLimitAfterLikelyLabel = 15;

        $extLimitAfterAmbiguousChar = 9;

        $extLimitWhenNotSure = 6;

        $possibleSeparatorsBetweenNumberAndExtLabel = "[ \xC2\xA0\\t,]*";

        // Optional full stop (.) or colon, followed by zero or more spaces/tabs/commas.

        $possibleCharsAfterExtLabel = "[:\\.\xEf\xBC\x8E]?[ \xC2\xA0\\t,-]*";

        $optionalExtnSuffix = '#?';

        // Here the extension is called out in more explicit way, i.e mentioning it obvious patterns

        // like "ext.". Canonical-equivalence doesn't seem to be an option with Android java, so we

        // allow two options for representing the accented o - the character itself, and one in the

        // unicode decomposed form with the combining acute accent.

        $explicitExtLabels = "(?:e?xt(?:ensi(?:o\xCC\x81?|\xC3\xB3))?n?|\xEF\xBD\x85?\xEF\xBD\x98\xEF\xBD\x94\xEF\xBD\x8E?|\xD0\xB4\xD0\xBE\xD0\xB1|anexo)";

        // One-character symbols that can be used to indicate an extension, and less commonly used

        // or more ambiguous extension labels.

        $ambiguousExtLabels = "(?:[x\xEF\xBD\x98#\xEF\xBC\x83~\xEF\xBD\x9E]|int|\xEF\xBD\x89\xEF\xBD\x8E\xEF\xBD\x94)";

        // When extension is not separated clearly.

        $ambiguousSeparator = '[- ]+';

        $rfcExtn = static::RFC3966_EXTN_PREFIX . static::extnDigits($extLimitAfterExplicitLabel);

        $explicitExtn = $possibleSeparatorsBetweenNumberAndExtLabel . $explicitExtLabels

            . $possibleCharsAfterExtLabel . static::extnDigits($extLimitAfterExplicitLabel)

            . $optionalExtnSuffix;

        $ambiguousExtn = $possibleSeparatorsBetweenNumberAndExtLabel . $ambiguousExtLabels

            . $possibleCharsAfterExtLabel . static::extnDigits($extLimitAfterAmbiguousChar) . $optionalExtnSuffix;

        $americanStyleExtnWithSuffix = $ambiguousSeparator . static::extnDigits($extLimitWhenNotSure) . '#';

        // The first regular expression covers RFC 3966 format, where the extension is added using

        // ";ext=". The second more generic where extension is mentioned with explicit labels like

        // "ext:". In both the above cases we allow more numbers in extension than any other extension

        // labels. The third one captures when single character extension labels or less commonly used

        // labels are used. In such cases we capture fewer extension digits in order to reduce the

        // chance of falsely interpreting two numbers beside each other as a number + extension. The

        // fourth one covers the special case of American numbers where the extension is written with a

        // hash at the end, such as "- 503#".

        $extensionPattern =

            $rfcExtn . '|'

            . $explicitExtn . '|'

            . $ambiguousExtn . '|'

            . $americanStyleExtnWithSuffix;

        // Additional pattern that is supported when parsing extensions, not when matching.

        if ($forParsing) {

            // This is same as possibleSeparatorsBetweenNumberAndExtLabel, but not matching comma as

            // extension label may have it.

            $possibleSeparatorsNumberExtLabelNoComma = "[ \xC2\xA0\\t]*";

            // ",," is commonly used for auto dialling the extension when connected. First comma is matched

            // through possibleSeparatorsBetweenNumberAndExtLabel, so we do not repeat it here. Semi-colon

            // works in Iphone and Android also to pop up a button with the extension number following.

            $autoDiallingAndExtLabelsFound = '(?:,{2}|;)';

            $autoDiallingExtn = $possibleSeparatorsNumberExtLabelNoComma

                . $autoDiallingAndExtLabelsFound . $possibleCharsAfterExtLabel

                . static::extnDigits($extLimitAfterLikelyLabel) . $optionalExtnSuffix;

            $onlyCommasExtn = $possibleSeparatorsNumberExtLabelNoComma

                . '(?:,)+' . $possibleCharsAfterExtLabel . static::extnDigits($extLimitAfterAmbiguousChar)

                . $optionalExtnSuffix;

            // Here the first pattern is exclusively for extension autodialling formats which are used

            // when dialling and in this case we accept longer extensions. However, the second pattern

            // is more liberal on the number of commas that acts as extension labels, so we have a strict

            // cap on the number of digits in such extensions.

            return $extensionPattern . '|'

                . $autoDiallingExtn . '|'

                . $onlyCommasExtn;

        }

        return $extensionPattern;

    }

    protected static function initExtnPattern(): void

    {

        static::$EXTN_PATTERN = '/(?:' . static::$EXTN_PATTERNS_FOR_PARSING . ')$/' . static::REGEX_FLAGS;

    }

    protected static function initValidPhoneNumberPatterns(): void

    {

        static::initExtnPatterns();

        static::$MIN_LENGTH_PHONE_NUMBER_PATTERN = '[' . static::DIGITS . ']{' . static::MIN_LENGTH_FOR_NSN . '}';

        static::$VALID_PHONE_NUMBER = '[' . static::PLUS_CHARS . ']*(?:[' . static::VALID_PUNCTUATION . static::STAR_SIGN . ']*[' . static::DIGITS . ']){3,}[' . static::VALID_PUNCTUATION . static::STAR_SIGN . static::VALID_ALPHA . static::DIGITS . ']*';

        static::$VALID_PHONE_NUMBER_PATTERN = '%^' . static::$MIN_LENGTH_PHONE_NUMBER_PATTERN . '$|^' . static::$VALID_PHONE_NUMBER . '(?:' . static::$EXTN_PATTERNS_FOR_PARSING . ')?$%' . static::REGEX_FLAGS;

    }

    /**

     * Used for testing purposes only to reset the PhoneNumberUtil singleton to null.

     */

    public static function resetInstance(): void

    {

        static::$instance = null;

    }

    /**

     * Converts all alpha characters in a number to their respective digits on a keypad, but retains

     * existing formatting.

     */

    public static function convertAlphaCharactersInNumber(string $number): string

    {

        return static::normalizeHelper($number, static::ALPHA_PHONE_MAPPINGS, false);

    }

    /**

     * Normalizes a string of characters representing a phone number by replacing all characters found

     * in the accompanying map with the values therein, and stripping all other characters if

     * removeNonMatches is true.

     *

     * @param string $number a string of characters representing a phone number

     * @param array<string,string> $normalizationReplacements a mapping of characters to what they should be replaced by in

     * the normalized version of the phone number.

     * @param bool $removeNonMatches indicates whether characters that are not able to be replaced.

     * should be stripped from the number. If this is false, they will be left unchanged in the number.

     * @return string the normalized string version of the phone number.

     */

    protected static function normalizeHelper(string $number, array $normalizationReplacements, bool $removeNonMatches): string

    {

        $normalizedNumber = '';

        $strLength = mb_strlen($number, 'UTF-8');

        for ($i = 0; $i < $strLength; $i++) {

            $character = mb_substr($number, $i, 1, 'UTF-8');

            if (isset($normalizationReplacements[mb_strtoupper($character, 'UTF-8')])) {

                $normalizedNumber .= $normalizationReplacements[mb_strtoupper($character, 'UTF-8')];

            } elseif (!$removeNonMatches) {

                $normalizedNumber .= $character;

            }

            // If neither of the above are true, we remove this character.

        }

        return $normalizedNumber;

    }

    /**

     * Helper function to check if the national prefix formatting rule has the first group only, i.e.,

     * does not start with the national prefix.

     */

    public static function formattingRuleHasFirstGroupOnly(string $nationalPrefixFormattingRule): bool

    {

        $firstGroupOnlyPrefixPatternMatcher = new Matcher(

            static::FIRST_GROUP_ONLY_PREFIX_PATTERN,

            $nationalPrefixFormattingRule

        );

        return $nationalPrefixFormattingRule === ''

            || $firstGroupOnlyPrefixPatternMatcher->matches();

    }

    /**

     * Returns all regions the library has metadata for.

     *

     * @return string[] An unordered array of the two-letter region codes for every geographical region the

     *  library supports

     */

    public function getSupportedRegions(): array

    {

        return $this->supportedRegions;

    }

    /**

     * Returns all global network calling codes the library has metadata for.

     *

     * @return int[] An unordered array of the country calling codes for every non-geographical entity

     *  the library supports

     */

    public function getSupportedGlobalNetworkCallingCodes(): array

    {

        return $this->countryCodesForNonGeographicalRegion;

    }

    /**

     * Returns all country calling codes the library has metadata for, covering both non-geographical

     * entities (global network calling codes) and those used for geographical entities. This could be

     * used to populate a drop-down box of country calling codes for a phone-number widget, for

     * instance.

     *

     * @return int[] An unordered array of the country calling codes for every geographical and

     *      non-geographical entity the library supports

     */

    public function getSupportedCallingCodes(): array

    {

        return array_keys($this->countryCallingCodeToRegionCodeMap);

    }

    /**

     * Returns true if there is any possible number data set for a particular PhoneNumberDesc.

     */

    protected static function descHasPossibleNumberData(PhoneNumberDesc $desc): bool

    {

        // If this is empty, it means numbers of this type inherit from the "general desc" -> the value

        // '-1' means that no numbers exist for this type.

        $possibleLength = $desc->getPossibleLength();

        return count($possibleLength) !== 1 || $possibleLength[0] !== -1;

    }

    /**

     * Returns true if there is any data set for a particular PhoneNumberDesc.

     */

    protected static function descHasData(PhoneNumberDesc $desc): bool

    {

        // Checking most properties since we don't know what's present, since a custom build may have

        // stripped just one of them (e.g. liteBuild strips exampleNumber). We don't bother checking the

        // possibleLengthsLocalOnly, since if this is the only thing that's present we don't really

        // support the type at all: no type-specific methods will work with only this data.

        return $desc->hasExampleNumber()

            || static::descHasPossibleNumberData($desc)

            || $desc->hasNationalNumberPattern();

    }

    /**

     * Returns the types we have metadata for based on the PhoneMetadata object passed in.

     *

     * @return array<int>

     */

    private function getSupportedTypesForMetadata(PhoneMetadata $metadata): array

    {

        $types = [];

        foreach (array_keys(PhoneNumberType::values()) as $type) {

            if ($type === PhoneNumberType::FIXED_LINE_OR_MOBILE || $type === PhoneNumberType::UNKNOWN) {

                // Never return FIXED_LINE_OR_MOBILE (it is a convenience type, and represents that a

                // particular number type can't be determined) or UNKNOWN (the non-type).

                continue;

            }

            if (self::descHasData($this->getNumberDescByType($metadata, $type))) {

                $types[] = $type;

            }

        }

        return $types;

    }

    /**

     * Returns the types for a given region which the library has metadata for. Will not include

     * FIXED_LINE_OR_MOBILE (if the numbers in this region could be classified as FIXED_LINE_OR_MOBILE,

     * both FIXED_LINE and MOBILE would be present) and UNKNOWN.

     *

     * No types will be returned for invalid or unknown region codes.

     *

     * @return array<int> Array of PhoneNumberType's

     */

    public function getSupportedTypesForRegion(string $regionCode): array

    {

        $metadata = $this->getMetadataForRegion($regionCode);

        if ($metadata === null) {

            return [];

        }

        return $this->getSupportedTypesForMetadata($metadata);

    }

    /**

     * Returns the types for a country-code belonging to a non-geographical entity which the library

     * has metadata for. Will not include FIXED_LINE_OR_MOBILE (if numbers for this non-geographical

     * entity could be classified as FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would be

     * present) and UNKNOWN.

     * @return array<int> Array of PhoneNumberType's

     */

    public function getSupportedTypesForNonGeoEntity(int $countryCallingCode): array

    {

        $metadata = $this->getMetadataForNonGeographicalRegion($countryCallingCode);

        if ($metadata === null) {

            return [];

        }

        return $this->getSupportedTypesForMetadata($metadata);

    }

    /**

     * Gets the length of the geographical area code from the {@code nationalNumber} field of the

     * PhoneNumber object passed in, so that clients could use it to split a national significant

     * number into geographical area code and subscriber number. It works in such a way that the

     * resultant subscriber number should be diallable, at least on some devices. An example of how

     * this could be used:

     *

     * <code>

     * $phoneUtil = PhoneNumberUtil::getInstance();

     * $number = $phoneUtil->parse("16502530000", "US");

     * $nationalSignificantNumber = $phoneUtil->getNationalSignificantNumber($number);

     *

     * $areaCodeLength = $phoneUtil->getLengthOfGeographicalAreaCode($number);

     * if ($areaCodeLength > 0)

     * {

     *     $areaCode = substr($nationalSignificantNumber, 0,$areaCodeLength);

     *     $subscriberNumber = substr($nationalSignificantNumber, $areaCodeLength);

     * } else {

     *     $areaCode = "";

     *     $subscriberNumber = $nationalSignificantNumber;

     * }

     * </code>

     *

     * N.B.: area code is a very ambiguous concept, so the I18N team generally recommends against

     * using it for most purposes, but recommends using the more general {@code nationalNumber}

     * instead. Read the following carefully before deciding to use this method:

     * <ul>

     *  <li> geographical area codes change over time, and this method honors those changes;

     *    therefore, it doesn't guarantee the stability of the result it produces.

     *  <li> subscriber numbers may not be diallable from all devices (notably mobile devices, which

     *    typically requires the full national_number to be dialled in most regions).

     *  <li> most non-geographical numbers have no area codes, including numbers from non-geographical

     *    entities

     *  <li> some geographical numbers have no area codes.

     * </ul>

     *

     * @param PhoneNumber $number PhoneNumber object for which clients want to know the length of the area code.

     * @return int the length of area code of the PhoneNumber object passed in.

     */

    public function getLengthOfGeographicalAreaCode(PhoneNumber $number): int

    {

        $metadata = $this->getMetadataForRegion($this->getRegionCodeForNumber($number));

        if ($metadata === null) {

            return 0;

        }

        $countryCallingCode = $number->getCountryCode();

        // If a country doesn't use a national prefix, and this number doesn't have an Italian leading

        // zero, we assume it is a closed dialling plan with no area codes.

        // Note:this is our general assumption, but there are exceptions which are tracked in

        // COUNTRIES_WITHOUT_NATIONAL_PREFIX_WITH_AREA_CODES.

        if (!$metadata->hasNationalPrefix() && !$number->isItalianLeadingZero() && !in_array($countryCallingCode, static::COUNTRIES_WITHOUT_NATIONAL_PREFIX_WITH_AREA_CODES)) {

            return 0;

        }

        $type = $this->getNumberType($number);

        if ($type === PhoneNumberType::MOBILE

            // Note this is a rough heuristic; it doesn't cover Indonesia well, for example, where area

            // codes are present for some mobile phones but not for others. We have no better way of

            // representing this in the metadata at this point.

            && in_array($countryCallingCode, static::GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES)

        ) {

            return 0;

        }

        if (!$this->isNumberGeographical($type, $countryCallingCode)) {

            return 0;

        }

        return $this->getLengthOfNationalDestinationCode($number);

    }

    /**

     * Returns the metadata for the given region code or {@code null} if the region code is invalid

     * or unknown.

     */

    public function getMetadataForRegion(?string $regionCode): ?PhoneMetadata

    {

        if (!$this->isValidRegionCode($regionCode)) {

            return null;

        }

        return $this->metadataSource->getMetadataForRegion($regionCode);

    }

    /**

     * Helper function to check region code is not unknown or null.

     */

    protected function isValidRegionCode(?string $regionCode): bool

    {

        return $regionCode !== null && in_array(strtoupper($regionCode), $this->supportedRegions);

    }

    /**

     * Returns the region where a phone number is from. This could be used for geocoding at the region

     * level. Only guarantees correct results for valid, full numbers (not short-codes, or invalid

     * numbers).

     *

     * @param PhoneNumber $number the phone number whose origin we want to know

     * @return null|string  the region where the phone number is from, or null if no region matches this calling

     * code

     */

    public function getRegionCodeForNumber(PhoneNumber $number): ?string

    {

        $countryCode = $number->getCountryCode();

        if (!isset($this->countryCallingCodeToRegionCodeMap[$countryCode])) {

            return null;

        }

        $regions = $this->countryCallingCodeToRegionCodeMap[$countryCode];

        if (count($regions) === 1) {

            return $regions[0];

        }

        return $this->getRegionCodeForNumberFromRegionList($number, $regions);

    }

    /**

     * Returns the region code for a number from the list of region codes passing in.

     *

     * @param string[] $regionCodes

     */

    protected function getRegionCodeForNumberFromRegionList(PhoneNumber $number, array $regionCodes): ?string

    {

        $nationalNumber = $this->getNationalSignificantNumber($number);

        foreach ($regionCodes as $regionCode) {

            // If leadingDigits is present, use this. Otherwise, do full validation.

            // Metadata cannot be null because the region codes come from the country calling code map.

            /** @var PhoneMetadata $metadata */

            $metadata = $this->getMetadataForRegion($regionCode);

            if ($metadata->hasLeadingDigits()) {

                $nbMatches = preg_match(

                    '/' . $metadata->getLeadingDigits() . '/',

                    $nationalNumber,

                    $matches,

                    PREG_OFFSET_CAPTURE

                );

                if ($nbMatches > 0 && $matches[0][1] === 0) {

                    return $regionCode;

                }

            } elseif ($this->getNumberTypeHelper($nationalNumber, $metadata) !== PhoneNumberType::UNKNOWN) {

                return $regionCode;

            }

        }

        return null;

    }

    /**

     * Gets the national significant number of the phone number. Note a national significant number

     * doesn't contain a national prefix or any formatting.

     *

     * @param PhoneNumber $number the phone number for which the national significant number is needed

     * @return string the national significant number of the PhoneNumber object passed in

     */

    public function getNationalSignificantNumber(PhoneNumber $number): string

    {

        // If leading zero(s) have been set, we prefix this now. Note this is not a national prefix.

        $nationalNumber = '';

        if ($number->isItalianLeadingZero() && $number->getNumberOfLeadingZeros() > 0) {

            $zeros = str_repeat('0', $number->getNumberOfLeadingZeros());

            $nationalNumber .= $zeros;

        }

        $nationalNumber .= $number->getNationalNumber();

        return $nationalNumber;

    }

    /**

     * Returns the type of number passed in i.e Toll free, premium.

     *

     * @return int PhoneNumberType constant

     */

    protected function getNumberTypeHelper(string $nationalNumber, PhoneMetadata $metadata): int

    {

        if (!$this->isNumberMatchingDesc($nationalNumber, $metadata->getGeneralDesc())) {

            return PhoneNumberType::UNKNOWN;

        }

        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPremiumRate())) {

            return PhoneNumberType::PREMIUM_RATE;

        }

        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getTollFree())) {

            return PhoneNumberType::TOLL_FREE;

        }

        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getSharedCost())) {

            return PhoneNumberType::SHARED_COST;

        }

        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getVoip())) {

            return PhoneNumberType::VOIP;

        }

        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPersonalNumber())) {

            return PhoneNumberType::PERSONAL_NUMBER;

        }

        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPager())) {

            return PhoneNumberType::PAGER;

        }

        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getUan())) {

            return PhoneNumberType::UAN;

        }

        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getVoicemail())) {

            return PhoneNumberType::VOICEMAIL;

        }

        $isFixedLine = $this->isNumberMatchingDesc($nationalNumber, $metadata->getFixedLine());

        if ($isFixedLine) {

            if ($metadata->getSameMobileAndFixedLinePattern()) {

                return PhoneNumberType::FIXED_LINE_OR_MOBILE;

            }

            if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getMobile())) {

                return PhoneNumberType::FIXED_LINE_OR_MOBILE;

            }

            return PhoneNumberType::FIXED_LINE;

        }

        // Otherwise, test to see if the number is mobile. Only do this if certain that the patterns for

        // mobile and fixed line aren't the same.

        if (!$metadata->getSameMobileAndFixedLinePattern() &&

            $this->isNumberMatchingDesc($nationalNumber, $metadata->getMobile())

        ) {

            return PhoneNumberType::MOBILE;

        }

        return PhoneNumberType::UNKNOWN;

    }

    public function isNumberMatchingDesc(string $nationalNumber, PhoneNumberDesc $numberDesc): bool

    {

        // Check if any possible number lengths are present; if so, we use them to avoid checking the

        // validation pattern if they don't match. If they are absent, this means they match the general

        // description, which we have already checked before checking a specific number type.

        $actualLength = mb_strlen($nationalNumber);

        $possibleLengths = $numberDesc->getPossibleLength();

        if (count($possibleLengths) > 0 && !in_array($actualLength, $possibleLengths)) {

            return false;

        }

        return $this->matcherAPI->matchNationalNumber($nationalNumber, $numberDesc, false);

    }

    /**

     * isNumberGeographical(PhoneNumber)

     *

     * Tests whether a phone number has a geographical association. It checks if the number is

     * associated with a certain region in the country to which it belongs. Note that this doesn't

     * verify if the number is actually in use.

     *

     * isNumberGeographical(PhoneNumberType, $countryCallingCode)

     *

     * Tests whether a phone number has a geographical association, as represented by its type and the

     * country it belongs to.