Completed
Push — issue175 ( 14f739 )
by Joshua
11:04
created

PhoneNumberUtil::initValidPhoneNumberPatterns()   A

Complexity

Conditions 1
Paths 1

Size

Total Lines 8
Code Lines 6

Duplication

Lines 0
Ratio 0 %

Importance

Changes 0
Metric Value
dl 0
loc 8
rs 9.4285
c 0
b 0
f 0
cc 1
eloc 6
nc 1
nop 0
1
<?php
2
3
namespace libphonenumber;
4
5
use libphonenumber\Leniency\AbstractLeniency;
6
7
/**
8
 * Utility for international phone numbers. Functionality includes formatting, parsing and
9
 * validation.
10
 *
11
 * <p>If you use this library, and want to be notified about important changes, please sign up to
12
 * our <a href="http://groups.google.com/group/libphonenumber-discuss/about">mailing list</a>.
13
 *
14
 * NOTE: A lot of methods in this class require Region Code strings. These must be provided using
15
 * CLDR two-letter region-code format. These should be in upper-case. The list of the codes
16
 * can be found here:
17
 * http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html
18
 *
19
 * @author Shaopeng Jia
20
 * @see https://github.com/googlei18n/libphonenumber
21
 */
22
class PhoneNumberUtil
23
{
24
    /** Flags to use when compiling regular expressions for phone numbers */
25
    const REGEX_FLAGS = 'ui'; //Unicode and case insensitive
26
    // The minimum and maximum length of the national significant number.
27
    const MIN_LENGTH_FOR_NSN = 2;
28
    // The ITU says the maximum length should be 15, but we have found longer numbers in Germany.
29
    const MAX_LENGTH_FOR_NSN = 17;
30
31
    // We don't allow input strings for parsing to be longer than 250 chars. This prevents malicious
32
    // input from overflowing the regular-expression engine.
33
    const MAX_INPUT_STRING_LENGTH = 250;
34
35
    // The maximum length of the country calling code.
36
    const MAX_LENGTH_COUNTRY_CODE = 3;
37
38
    const REGION_CODE_FOR_NON_GEO_ENTITY = "001";
39
    const META_DATA_FILE_PREFIX = 'PhoneNumberMetadata';
40
    const TEST_META_DATA_FILE_PREFIX = 'PhoneNumberMetadataForTesting';
41
42
    // Region-code for the unknown region.
43
    const UNKNOWN_REGION = "ZZ";
44
45
    const NANPA_COUNTRY_CODE = 1;
46
    /*
47
     * The prefix that needs to be inserted in front of a Colombian landline number when dialed from
48
     * a mobile number in Colombia.
49
     */
50
    const COLOMBIA_MOBILE_TO_FIXED_LINE_PREFIX = "3";
51
    // The PLUS_SIGN signifies the international prefix.
52
    const PLUS_SIGN = '+';
53
    const PLUS_CHARS = '++';
54
    const STAR_SIGN = '*';
55
56
    const RFC3966_EXTN_PREFIX = ";ext=";
57
    const RFC3966_PREFIX = "tel:";
58
    const RFC3966_PHONE_CONTEXT = ";phone-context=";
59
    const RFC3966_ISDN_SUBADDRESS = ";isub=";
60
61
    // We use this pattern to check if the phone number has at least three letters in it - if so, then
62
    // we treat it as a number where some phone-number digits are represented by letters.
63
    const VALID_ALPHA_PHONE_PATTERN = "(?:.*?[A-Za-z]){3}.*";
64
    // We accept alpha characters in phone numbers, ASCII only, upper and lower case.
65
    const VALID_ALPHA = "A-Za-z";
66
67
68
    // Default extension prefix to use when formatting. This will be put in front of any extension
69
    // component of the number, after the main national number is formatted. For example, if you wish
70
    // the default extension formatting to be " extn: 3456", then you should specify " extn: " here
71
    // as the default extension prefix. This can be overridden by region-specific preferences.
72
    const DEFAULT_EXTN_PREFIX = " ext. ";
73
74
    // Regular expression of acceptable punctuation found in phone numbers. This excludes punctuation
75
    // found as a leading character only.
76
    // This consists of dash characters, white space characters, full stops, slashes,
77
    // square brackets, parentheses and tildes. It also includes the letter 'x' as that is found as a
78
    // placeholder for carrier information in some phone numbers. Full-width variants are also
79
    // present.
80
    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";
81
    const DIGITS = "\\p{Nd}";
82
83
    // Pattern that makes it easy to distinguish whether a region has a unique international dialing
84
    // prefix or not. If a region has a unique international prefix (e.g. 011 in USA), it will be
85
    // represented as a string that contains a sequence of ASCII digits. If there are multiple
86
    // available international prefixes in a region, they will be represented as a regex string that
87
    // always contains character(s) other than ASCII digits.
88
    // Note this regex also includes tilde, which signals waiting for the tone.
89
    const UNIQUE_INTERNATIONAL_PREFIX = "[\\d]+(?:[~\xE2\x81\x93\xE2\x88\xBC\xEF\xBD\x9E][\\d]+)?";
90
    const NON_DIGITS_PATTERN = "(\\D+)";
91
92
    // The FIRST_GROUP_PATTERN was originally set to $1 but there are some countries for which the
93
    // first group is not used in the national pattern (e.g. Argentina) so the $1 group does not match
94
    // correctly.  Therefore, we use \d, so that the first group actually used in the pattern will be
95
    // matched.
96
    const FIRST_GROUP_PATTERN = "(\\$\\d)";
97
    const NP_PATTERN = '\\$NP';
98
    const FG_PATTERN = '\\$FG';
99
    const CC_PATTERN = '\\$CC';
100
101
    // A pattern that is used to determine if the national prefix formatting rule has the first group
102
    // only, i.e., does not start with the national prefix. Note that the pattern explicitly allows
103
    // for unbalanced parentheses.
104
    const FIRST_GROUP_ONLY_PREFIX_PATTERN = '\\(?\\$1\\)?';
105
    public static $PLUS_CHARS_PATTERN;
106
    protected static $SEPARATOR_PATTERN;
107
    protected static $CAPTURING_DIGIT_PATTERN;
108
    protected static $VALID_START_CHAR_PATTERN = null;
109
    public static $SECOND_NUMBER_START_PATTERN = '[\\\\/] *x';
110
    public static $UNWANTED_END_CHAR_PATTERN = "[[\\P{N}&&\\P{L}]&&[^#]]+$";
111
    protected static $DIALLABLE_CHAR_MAPPINGS = array();
112
    protected static $CAPTURING_EXTN_DIGITS;
113
114
    /**
115
     * @var PhoneNumberUtil
116
     */
117
    protected static $instance = null;
118
119
    /**
120
     * Only upper-case variants of alpha characters are stored.
121
     * @var array
122
     */
123
    protected static $ALPHA_MAPPINGS = array(
124
        'A' => '2',
125
        'B' => '2',
126
        'C' => '2',
127
        'D' => '3',
128
        'E' => '3',
129
        'F' => '3',
130
        'G' => '4',
131
        'H' => '4',
132
        'I' => '4',
133
        'J' => '5',
134
        'K' => '5',
135
        'L' => '5',
136
        'M' => '6',
137
        'N' => '6',
138
        'O' => '6',
139
        'P' => '7',
140
        'Q' => '7',
141
        'R' => '7',
142
        'S' => '7',
143
        'T' => '8',
144
        'U' => '8',
145
        'V' => '8',
146
        'W' => '9',
147
        'X' => '9',
148
        'Y' => '9',
149
        'Z' => '9',
150
    );
151
152
    /**
153
     * Map of country calling codes that use a mobile token before the area code. One example of when
154
     * this is relevant is when determining the length of the national destination code, which should
155
     * be the length of the area code plus the length of the mobile token.
156
     * @var array
157
     */
158
    protected static $MOBILE_TOKEN_MAPPINGS = array();
159
160
    /**
161
     * Set of country codes that have geographically assigned mobile numbers (see GEO_MOBILE_COUNTRIES
162
     * below) which are not based on *area codes*. For example, in China mobile numbers start with a
163
     * carrier indicator, and beyond that are geographically assigned: this carrier indicator is not
164
     * considered to be an area code.
165
     *
166
     * @var array
167
     */
168
    protected static $GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES;
169
170
    /**
171
     * Set of country calling codes that have geographically assigned mobile numbers. This may not be
172
     * complete; we add calling codes case by case, as we find geographical mobile numbers or hear
173
     * from user reports. Note that countries like the US, where we can't distinguish between
174
     * fixed-line or mobile numbers, are not listed here, since we consider FIXED_LINE_OR_MOBILE to be
175
     * a possibly geographically-related type anyway (like FIXED_LINE).
176
     *
177
     * @var array
178
     */
179
    protected static $GEO_MOBILE_COUNTRIES;
180
181
    /**
182
     * For performance reasons, amalgamate both into one map.
183
     * @var array
184
     */
185
    protected static $ALPHA_PHONE_MAPPINGS = null;
186
187
    /**
188
     * Separate map of all symbols that we wish to retain when formatting alpha numbers. This
189
     * includes digits, ASCII letters and number grouping symbols such as "-" and " ".
190
     * @var array
191
     */
192
    protected static $ALL_PLUS_NUMBER_GROUPING_SYMBOLS;
193
194
    /**
195
     * Simple ASCII digits map used to populate ALPHA_PHONE_MAPPINGS and
196
     * ALL_PLUS_NUMBER_GROUPING_SYMBOLS.
197
     * @var array
198
     */
199
    protected static $asciiDigitMappings = array(
200
        '0' => '0',
201
        '1' => '1',
202
        '2' => '2',
203
        '3' => '3',
204
        '4' => '4',
205
        '5' => '5',
206
        '6' => '6',
207
        '7' => '7',
208
        '8' => '8',
209
        '9' => '9',
210
    );
211
212
    /**
213
     * Regexp of all possible ways to write extensions, for use when parsing. This will be run as a
214
     * case-insensitive regexp match. Wide character versions are also provided after each ASCII
215
     * version.
216
     * @var String
217
     */
218
    protected static $EXTN_PATTERNS_FOR_PARSING;
219
    /**
220
     * @var string
221
     * @internal
222
     */
223
    public static $EXTN_PATTERNS_FOR_MATCHING;
224
    protected static $EXTN_PATTERN = null;
225
    protected static $VALID_PHONE_NUMBER_PATTERN = null;
226
    protected static $MIN_LENGTH_PHONE_NUMBER_PATTERN;
227
    /**
228
     *  Regular expression of viable phone numbers. This is location independent. Checks we have at
229
     * least three leading digits, and only valid punctuation, alpha characters and
230
     * digits in the phone number. Does not include extension data.
231
     * The symbol 'x' is allowed here as valid punctuation since it is often used as a placeholder for
232
     * carrier codes, for example in Brazilian phone numbers. We also allow multiple "+" characters at
233
     * the start.
234
     * Corresponds to the following:
235
     * [digits]{minLengthNsn}|
236
     * plus_sign*(([punctuation]|[star])*[digits]){3,}([punctuation]|[star]|[digits]|[alpha])*
237
     *
238
     * The first reg-ex is to allow short numbers (two digits long) to be parsed if they are entered
239
     * as "15" etc, but only if there is no punctuation in them. The second expression restricts the
240
     * number of digits to three or more, but then allows them to be in international form, and to
241
     * have alpha-characters and punctuation.
242
     *
243
     * Note VALID_PUNCTUATION starts with a -, so must be the first in the range.
244
     * @var string
245
     */
246
    protected static $VALID_PHONE_NUMBER;
247
    protected static $numericCharacters = array(
248
        "\xef\xbc\x90" => 0,
249
        "\xef\xbc\x91" => 1,
250
        "\xef\xbc\x92" => 2,
251
        "\xef\xbc\x93" => 3,
252
        "\xef\xbc\x94" => 4,
253
        "\xef\xbc\x95" => 5,
254
        "\xef\xbc\x96" => 6,
255
        "\xef\xbc\x97" => 7,
256
        "\xef\xbc\x98" => 8,
257
        "\xef\xbc\x99" => 9,
258
259
        "\xd9\xa0" => 0,
260
        "\xd9\xa1" => 1,
261
        "\xd9\xa2" => 2,
262
        "\xd9\xa3" => 3,
263
        "\xd9\xa4" => 4,
264
        "\xd9\xa5" => 5,
265
        "\xd9\xa6" => 6,
266
        "\xd9\xa7" => 7,
267
        "\xd9\xa8" => 8,
268
        "\xd9\xa9" => 9,
269
270
        "\xdb\xb0" => 0,
271
        "\xdb\xb1" => 1,
272
        "\xdb\xb2" => 2,
273
        "\xdb\xb3" => 3,
274
        "\xdb\xb4" => 4,
275
        "\xdb\xb5" => 5,
276
        "\xdb\xb6" => 6,
277
        "\xdb\xb7" => 7,
278
        "\xdb\xb8" => 8,
279
        "\xdb\xb9" => 9,
280
281
        "\xe1\xa0\x90" => 0,
282
        "\xe1\xa0\x91" => 1,
283
        "\xe1\xa0\x92" => 2,
284
        "\xe1\xa0\x93" => 3,
285
        "\xe1\xa0\x94" => 4,
286
        "\xe1\xa0\x95" => 5,
287
        "\xe1\xa0\x96" => 6,
288
        "\xe1\xa0\x97" => 7,
289
        "\xe1\xa0\x98" => 8,
290
        "\xe1\xa0\x99" => 9,
291
    );
292
293
    /**
294
     * The set of county calling codes that map to the non-geo entity region ("001").
295
     * @var array
296
     */
297
    protected $countryCodesForNonGeographicalRegion = array();
298
    /**
299
     * The set of regions the library supports.
300
     * @var array
301
     */
302
    protected $supportedRegions = array();
303
304
    /**
305
     * A mapping from a country calling code to the region codes which denote the region represented
306
     * by that country calling code. In the case of multiple regions sharing a calling code, such as
307
     * the NANPA regions, the one indicated with "isMainCountryForCode" in the metadata should be
308
     * first.
309
     * @var array
310
     */
311
    protected $countryCallingCodeToRegionCodeMap = array();
312
    /**
313
     * The set of regions that share country calling code 1.
314
     * @var array
315
     */
316
    protected $nanpaRegions = array();
317
318
    /**
319
     * @var MetadataSourceInterface
320
     */
321
    protected $metadataSource;
322
323
    /**
324
     * This class implements a singleton, so the only constructor is protected.
325
     * @param MetadataSourceInterface $metadataSource
326
     * @param $countryCallingCodeToRegionCodeMap
327
     */
328
    protected function __construct(MetadataSourceInterface $metadataSource, $countryCallingCodeToRegionCodeMap)
329
    {
330
        $this->metadataSource = $metadataSource;
331
        $this->countryCallingCodeToRegionCodeMap = $countryCallingCodeToRegionCodeMap;
332
        $this->init();
333
        static::initCapturingExtnDigits();
334
        static::initExtnPatterns();
335
        static::initExtnPattern();
336
        static::$PLUS_CHARS_PATTERN = "[" . static::PLUS_CHARS . "]+";
337
        static::$SEPARATOR_PATTERN = "[" . static::VALID_PUNCTUATION . "]+";
338
        static::$CAPTURING_DIGIT_PATTERN = "(" . static::DIGITS . ")";
339
        static::initValidStartCharPattern();
340
        static::initAlphaPhoneMappings();
341
        static::initDiallableCharMappings();
342
343
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS = array();
344
        // Put (lower letter -> upper letter) and (upper letter -> upper letter) mappings.
345
        foreach (static::$ALPHA_MAPPINGS as $c => $value) {
346
            static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS[strtolower($c)] = $c;
347
            static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS[$c] = $c;
348
        }
349
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS += static::$asciiDigitMappings;
350
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["-"] = '-';
351
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xEF\xBC\x8D"] = '-';
352
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x90"] = '-';
353
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x91"] = '-';
354
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x92"] = '-';
355
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x93"] = '-';
356
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x94"] = '-';
357
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x95"] = '-';
358
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x88\x92"] = '-';
359
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["/"] = "/";
360
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xEF\xBC\x8F"] = "/";
361
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS[" "] = " ";
362
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE3\x80\x80"] = " ";
363
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x81\xA0"] = " ";
364
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["."] = ".";
365
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xEF\xBC\x8E"] = ".";
366
367
368
        static::initValidPhoneNumberPatterns();
369
370
        static::$UNWANTED_END_CHAR_PATTERN = "[^" . static::DIGITS . static::VALID_ALPHA . "#]+$";
371
372
        static::initMobileTokenMappings();
373
374
        static::$GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES = array();
375
        static::$GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES[] = 86; // China
376
377
        static::$GEO_MOBILE_COUNTRIES = array();
378
        static::$GEO_MOBILE_COUNTRIES[] = 52; // Mexico
379
        static::$GEO_MOBILE_COUNTRIES[] = 54; // Argentina
380
        static::$GEO_MOBILE_COUNTRIES[] = 55; // Brazil
381
        static::$GEO_MOBILE_COUNTRIES[] = 62; // Indonesia: some prefixes only (fixed CMDA wireless)
382
383
        static::$GEO_MOBILE_COUNTRIES = array_merge(static::$GEO_MOBILE_COUNTRIES, static::$GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES);
384
    }
385
386
    /**
387
     * Gets a {@link PhoneNumberUtil} instance to carry out international phone number formatting,
388
     * parsing, or validation. The instance is loaded with phone number metadata for a number of most
389
     * commonly used regions.
390
     *
391
     * <p>The {@link PhoneNumberUtil} is implemented as a singleton. Therefore, calling getInstance
392
     * multiple times will only result in one instance being created.
393
     *
394
     * @param string $baseFileLocation
395
     * @param array|null $countryCallingCodeToRegionCodeMap
396
     * @param MetadataLoaderInterface|null $metadataLoader
397
     * @param MetadataSourceInterface|null $metadataSource
398
     * @return PhoneNumberUtil instance
399
     */
400
    public static function getInstance($baseFileLocation = self::META_DATA_FILE_PREFIX, array $countryCallingCodeToRegionCodeMap = null, MetadataLoaderInterface $metadataLoader = null, MetadataSourceInterface $metadataSource = null)
401
    {
402
        if (static::$instance === null) {
403
            if ($countryCallingCodeToRegionCodeMap === null) {
404
                $countryCallingCodeToRegionCodeMap = CountryCodeToRegionCodeMap::$countryCodeToRegionCodeMap;
405
            }
406
407
            if ($metadataLoader === null) {
408
                $metadataLoader = new DefaultMetadataLoader();
409
            }
410
411
            if ($metadataSource === null) {
412
                $metadataSource = new MultiFileMetadataSourceImpl($metadataLoader, __DIR__ . '/data/' . $baseFileLocation);
413
            }
414
415
            static::$instance = new static($metadataSource, $countryCallingCodeToRegionCodeMap);
416
        }
417
        return static::$instance;
418
    }
419
420
    protected function init()
421
    {
422
        foreach ($this->countryCallingCodeToRegionCodeMap as $countryCode => $regionCodes) {
423
            // We can assume that if the country calling code maps to the non-geo entity region code then
424
            // that's the only region code it maps to.
425
            if (count($regionCodes) == 1 && static::REGION_CODE_FOR_NON_GEO_ENTITY === $regionCodes[0]) {
426
                // This is the subset of all country codes that map to the non-geo entity region code.
427
                $this->countryCodesForNonGeographicalRegion[] = $countryCode;
428
            } else {
429
                // The supported regions set does not include the "001" non-geo entity region code.
430
                $this->supportedRegions = array_merge($this->supportedRegions, $regionCodes);
431
            }
432
        }
433
        // If the non-geo entity still got added to the set of supported regions it must be because
434
        // there are entries that list the non-geo entity alongside normal regions (which is wrong).
435
        // If we discover this, remove the non-geo entity from the set of supported regions and log.
436
        $idx_region_code_non_geo_entity = array_search(static::REGION_CODE_FOR_NON_GEO_ENTITY, $this->supportedRegions);
437
        if ($idx_region_code_non_geo_entity !== false) {
438
            unset($this->supportedRegions[$idx_region_code_non_geo_entity]);
439
        }
440
        $this->nanpaRegions = $this->countryCallingCodeToRegionCodeMap[static::NANPA_COUNTRY_CODE];
441
    }
442
443
    /**
444
     * @internal
445
     */
446
    public static function initCapturingExtnDigits()
447
    {
448
        static::$CAPTURING_EXTN_DIGITS = "(" . static::DIGITS . "{1,7})";
449
    }
450
451
    /**
452
     * @internal
453
     */
454
    public static function initExtnPatterns()
455
    {
456
        // One-character symbols that can be used to indicate an extension.
457
        $singleExtnSymbolsForMatching = "x\xEF\xBD\x98#\xEF\xBC\x83~\xEF\xBD\x9E";
458
        // For parsing, we are slightly more lenient in our interpretation than for matching. Here we
459
        // allow "comma" and "semicolon" as possible extension indicators. When matching, these are
460
        // hardly ever used to indicate this.
461
        $singleExtnSymbolsForParsing = ",;" . $singleExtnSymbolsForMatching;
462
463
        static::$EXTN_PATTERNS_FOR_PARSING = static::createExtnPattern($singleExtnSymbolsForParsing);
464
        static::$EXTN_PATTERNS_FOR_MATCHING = static::createExtnPattern($singleExtnSymbolsForMatching);
465
    }
466
467
    /**
468
     * Helper initialiser method to create the regular-expression pattern to match extensions,
469
     * allowing the one-char extension symbols provided by {@code singleExtnSymbols}.
470
     * @param string $singleExtnSymbols
471
     * @return string
472
     */
473
    protected static function createExtnPattern($singleExtnSymbols)
474
    {
475
        // There are three regular expressions here. The first covers RFC 3966 format, where the
476
        // extension is added using ";ext=". The second more generic one starts with optional white
477
        // space and ends with an optional full stop (.), followed by zero or more spaces/tabs/commas
478
        // and then the numbers themselves. The other one covers the special case of American numbers
479
        // where the extension is written with a hash at the end, such as "- 503#"
480
        // Note that the only capturing groups should be around the digits that you want to capture as
481
        // part of the extension, or else parsing will fail!
482
        // Canonical-equivalence doesn't seem to be an option with Android java, so we allow two options
483
        // for representing the accented o - the character itself, and one in the unicode decomposed
484
        // form with the combining acute accent.
485
        return (static::RFC3966_EXTN_PREFIX . static::$CAPTURING_EXTN_DIGITS . "|" . "[ \xC2\xA0\\t,]*" .
486
            "(?:e?xt(?:ensi(?:o\xCC\x81?|\xC3\xB3))?n?|(?:\xEF\xBD\x85)?\xEF\xBD\x98\xEF\xBD\x94(?:\xEF\xBD\x8E)?|" .
487
            "[" . $singleExtnSymbols . "]|int|\xEF\xBD\x89\xEF\xBD\x8E\xEF\xBD\x94|anexo)" .
488
            "[:\\.\xEF\xBC\x8E]?[ \xC2\xA0\\t,-]*" . static::$CAPTURING_EXTN_DIGITS . "\\#?|" .
489
            "[- ]+(" . static::DIGITS . "{1,5})\\#");
490
    }
491
492
    protected static function initExtnPattern()
493
    {
494
        static::$EXTN_PATTERN = "/(?:" . static::$EXTN_PATTERNS_FOR_PARSING . ")$/" . static::REGEX_FLAGS;
495
    }
496
497
    protected static function initValidPhoneNumberPatterns()
498
    {
499
        static::initCapturingExtnDigits();
500
        static::initExtnPatterns();
501
        static::$MIN_LENGTH_PHONE_NUMBER_PATTERN = "[" . static::DIGITS . "]{" . static::MIN_LENGTH_FOR_NSN . "}";
502
        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 . "]*";
503
        static::$VALID_PHONE_NUMBER_PATTERN = "%^" . static::$MIN_LENGTH_PHONE_NUMBER_PATTERN . "$|^" . static::$VALID_PHONE_NUMBER . "(?:" . static::$EXTN_PATTERNS_FOR_PARSING . ")?$%" . static::REGEX_FLAGS;
504
    }
505
506
    protected static function initAlphaPhoneMappings()
507
    {
508
        static::$ALPHA_PHONE_MAPPINGS = static::$ALPHA_MAPPINGS + static::$asciiDigitMappings;
509
    }
510
511
    protected static function initValidStartCharPattern()
512
    {
513
        static::$VALID_START_CHAR_PATTERN = "[" . static::PLUS_CHARS . static::DIGITS . "]";
514
    }
515
516
    protected static function initMobileTokenMappings()
517
    {
518
        static::$MOBILE_TOKEN_MAPPINGS = array();
519
        static::$MOBILE_TOKEN_MAPPINGS['52'] = "1";
520
        static::$MOBILE_TOKEN_MAPPINGS['54'] = "9";
521
    }
522
523
    protected static function initDiallableCharMappings()
524
    {
525
        static::$DIALLABLE_CHAR_MAPPINGS = static::$asciiDigitMappings;
526
        static::$DIALLABLE_CHAR_MAPPINGS[static::PLUS_SIGN] = static::PLUS_SIGN;
527
        static::$DIALLABLE_CHAR_MAPPINGS['*'] = '*';
528
        static::$DIALLABLE_CHAR_MAPPINGS['#'] = '#';
529
    }
530
531
    /**
532
     * Used for testing purposes only to reset the PhoneNumberUtil singleton to null.
533
     */
534
    public static function resetInstance()
535
    {
536
        static::$instance = null;
537
    }
538
539
    /**
540
     * Converts all alpha characters in a number to their respective digits on a keypad, but retains
541
     * existing formatting.
542
     * @param string $number
543
     * @return string
544
     */
545
    public static function convertAlphaCharactersInNumber($number)
546
    {
547
        if (static::$ALPHA_PHONE_MAPPINGS === null) {
548
            static::initAlphaPhoneMappings();
549
        }
550
551
        return static::normalizeHelper($number, static::$ALPHA_PHONE_MAPPINGS, false);
552
    }
553
554
    /**
555
     * Normalizes a string of characters representing a phone number by replacing all characters found
556
     * in the accompanying map with the values therein, and stripping all other characters if
557
     * removeNonMatches is true.
558
     *
559
     * @param string $number a string of characters representing a phone number
560
     * @param array $normalizationReplacements a mapping of characters to what they should be replaced by in
561
     * the normalized version of the phone number
562
     * @param bool $removeNonMatches indicates whether characters that are not able to be replaced
563
     * should be stripped from the number. If this is false, they will be left unchanged in the number.
564
     * @return string the normalized string version of the phone number
565
     */
566
    protected static function normalizeHelper($number, array $normalizationReplacements, $removeNonMatches)
567
    {
568
        $normalizedNumber = "";
569
        $strLength = mb_strlen($number, 'UTF-8');
570
        for ($i = 0; $i < $strLength; $i++) {
571
            $character = mb_substr($number, $i, 1, 'UTF-8');
572
            if (isset($normalizationReplacements[mb_strtoupper($character, 'UTF-8')])) {
573
                $normalizedNumber .= $normalizationReplacements[mb_strtoupper($character, 'UTF-8')];
574
            } else {
575
                if (!$removeNonMatches) {
576
                    $normalizedNumber .= $character;
577
                }
578
            }
579
            // If neither of the above are true, we remove this character.
580
        }
581
        return $normalizedNumber;
582
    }
583
584
    /**
585
     * Helper function to check if the national prefix formatting rule has the first group only, i.e.,
586
     * does not start with the national prefix.
587
     * @param string $nationalPrefixFormattingRule
588
     * @return bool
589
     */
590
    public static function formattingRuleHasFirstGroupOnly($nationalPrefixFormattingRule)
591
    {
592
        $firstGroupOnlyPrefixPatternMatcher = new Matcher(static::FIRST_GROUP_ONLY_PREFIX_PATTERN,
593
            $nationalPrefixFormattingRule);
594
595
        return mb_strlen($nationalPrefixFormattingRule) === 0
596
            || $firstGroupOnlyPrefixPatternMatcher->matches();
597
    }
598
599
    /**
600
     * Returns all regions the library has metadata for.
601
     *
602
     * @return array An unordered array of the two-letter region codes for every geographical region the
603
     *  library supports
604
     */
605
    public function getSupportedRegions()
606
    {
607
        return $this->supportedRegions;
608
    }
609
610
    /**
611
     * Returns all global network calling codes the library has metadata for.
612
     *
613
     * @return array An unordered array of the country calling codes for every non-geographical entity
614
     *  the library supports
615
     */
616
    public function getSupportedGlobalNetworkCallingCodes()
617
    {
618
        return $this->countryCodesForNonGeographicalRegion;
619
    }
620
621
    /**
622
     * Returns true if there is any possible number data set for a particular PhoneNumberDesc.
623
     *
624
     * @param PhoneNumberDesc $desc
625
     * @return bool
626
     */
627
    protected static function descHasPossibleNumberData(PhoneNumberDesc $desc)
628
    {
629
        // If this is empty, it means numbers of this type inherit from the "general desc" -> the value
630
        // '-1' means that no numbers exist for this type.
631
        $possibleLength = $desc->getPossibleLength();
632
        return count($possibleLength) != 1 || $possibleLength[0] != -1;
633
    }
634
635
    /**
636
     * Returns true if there is any data set for a particular PhoneNumberDesc.
637
     *
638
     * @param PhoneNumberDesc $desc
639
     * @return bool
640
     */
641
    protected static function descHasData(PhoneNumberDesc $desc)
642
    {
643
        // Checking most properties since we don't know what's present, since a custom build may have
644
        // stripped just one of them (e.g. liteBuild strips exampleNumber). We don't bother checking the
645
        // possibleLengthsLocalOnly, since if this is the only thing that's present we don't really
646
        // support the type at all: no type-specific methods will work with only this data.
647
        return $desc->hasExampleNumber()
648
            || static::descHasPossibleNumberData($desc)
649
            || ($desc->hasNationalNumberPattern() && $desc->getNationalNumberPattern() != 'NA');
650
    }
651
652
    /**
653
     * Returns the types we have metadata for based on the PhoneMetadata object passed in
654
     *
655
     * @param PhoneMetadata $metadata
656
     * @return array
657
     */
658
    private function getSupportedTypesForMetadata(PhoneMetadata $metadata)
659
    {
660
        $types = array();
661
        foreach (array_keys(PhoneNumberType::values()) as $type) {
662
            if ($type === PhoneNumberType::FIXED_LINE_OR_MOBILE || $type === PhoneNumberType::UNKNOWN) {
663
                // Never return FIXED_LINE_OR_MOBILE (it is a convenience type, and represents that a
664
                // particular number type can't be determined) or UNKNOWN (the non-type).
665
                continue;
666
            }
667
668
            if ($this->descHasData($this->getNumberDescByType($metadata, $type))) {
669
                $types[] = $type;
670
            }
671
        }
672
673
        return $types;
674
    }
675
676
    /**
677
     * Returns the types for a given region which the library has metadata for. Will not include
678
     * FIXED_LINE_OR_MOBILE (if the numbers in this region could be classified as FIXED_LINE_OR_MOBILE,
679
     * both FIXED_LINE and MOBILE would be present) and UNKNOWN.
680
     *
681
     * No types will be returned for invalid or unknown region codes.
682
     *
683
     * @param string $regionCode
684
     * @return array
685
     */
686
    public function getSupportedTypesForRegion($regionCode)
687
    {
688
        if (!$this->isValidRegionCode($regionCode)) {
689
            return array();
690
        }
691
        $metadata = $this->getMetadataForRegion($regionCode);
692
        return $this->getSupportedTypesForMetadata($metadata);
0 ignored issues
show
Bug introduced by
It seems like $metadata defined by $this->getMetadataForRegion($regionCode) on line 691 can be null; however, libphonenumber\PhoneNumb...ortedTypesForMetadata() does not accept null, maybe add an additional type check?

Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code:

/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
693
    }
694
695
    /**
696
     * Returns the types for a country-code belonging to a non-geographical entity which the library
697
     * has metadata for. Will not include FIXED_LINE_OR_MOBILE (if numbers for this non-geographical
698
     * entity could be classified as FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would be
699
     * present) and UNKNOWN.
700
     *
701
     * @param int $countryCallingCode
702
     * @return array
703
     */
704
    public function getSupportedTypesForNonGeoEntity($countryCallingCode)
705
    {
706
        $metadata = $this->getMetadataForNonGeographicalRegion($countryCallingCode);
707
        if ($metadata === null) {
708
            return array();
709
        }
710
711
        return $this->getSupportedTypesForMetadata($metadata);
712
    }
713
714
    /**
715
     * Gets the length of the geographical area code from the {@code nationalNumber} field of the
716
     * PhoneNumber object passed in, so that clients could use it to split a national significant
717
     * number into geographical area code and subscriber number. It works in such a way that the
718
     * resultant subscriber number should be diallable, at least on some devices. An example of how
719
     * this could be used:
720
     *
721
     * <code>
722
     * $phoneUtil = PhoneNumberUtil::getInstance();
723
     * $number = $phoneUtil->parse("16502530000", "US");
724
     * $nationalSignificantNumber = $phoneUtil->getNationalSignificantNumber($number);
725
     *
726
     * $areaCodeLength = $phoneUtil->getLengthOfGeographicalAreaCode($number);
727
     * if ($areaCodeLength > 0)
728
     * {
729
     *     $areaCode = substr($nationalSignificantNumber, 0,$areaCodeLength);
730
     *     $subscriberNumber = substr($nationalSignificantNumber, $areaCodeLength);
731
     * } else {
732
     *     $areaCode = "";
733
     *     $subscriberNumber = $nationalSignificantNumber;
734
     * }
735
     * </code>
736
     *
737
     * N.B.: area code is a very ambiguous concept, so the I18N team generally recommends against
738
     * using it for most purposes, but recommends using the more general {@code nationalNumber}
739
     * instead. Read the following carefully before deciding to use this method:
740
     * <ul>
741
     *  <li> geographical area codes change over time, and this method honors those changes;
742
     *    therefore, it doesn't guarantee the stability of the result it produces.
743
     *  <li> subscriber numbers may not be diallable from all devices (notably mobile devices, which
744
     *    typically requires the full national_number to be dialled in most regions).
745
     *  <li> most non-geographical numbers have no area codes, including numbers from non-geographical
746
     *    entities
747
     *  <li> some geographical numbers have no area codes.
748
     * </ul>
749
     * @param PhoneNumber $number PhoneNumber object for which clients want to know the length of the area code.
750
     * @return int the length of area code of the PhoneNumber object passed in.
751
     */
752
    public function getLengthOfGeographicalAreaCode(PhoneNumber $number)
753
    {
754
        $metadata = $this->getMetadataForRegion($this->getRegionCodeForNumber($number));
755
        if ($metadata === null) {
756
            return 0;
757
        }
758
        // If a country doesn't use a national prefix, and this number doesn't have an Italian leading
759
        // zero, we assume it is a closed dialling plan with no area codes.
760
        if (!$metadata->hasNationalPrefix() && !$number->isItalianLeadingZero()) {
0 ignored issues
show
Bug Best Practice introduced by
The expression $number->isItalianLeadingZero() of type boolean|null is loosely compared to false; this is ambiguous if the boolean can be false. You might want to explicitly use !== null instead.

If an expression can have both false, and null as possible values. It is generally a good practice to always use strict comparison to clearly distinguish between those two values.

$a = canBeFalseAndNull();

// Instead of
if ( ! $a) { }

// Better use one of the explicit versions:
if ($a !== null) { }
if ($a !== false) { }
if ($a !== null && $a !== false) { }
Loading history...
761
            return 0;
762
        }
763
764
        $type = $this->getNumberType($number);
765
        $countryCallingCode = $number->getCountryCode();
766
767
        if ($type === PhoneNumberType::MOBILE
768
            // Note this is a rough heuristic; it doesn't cover Indonesia well, for example, where area
769
            // codes are present for some mobile phones but not for others. We have no better way of
770
            // representing this in the metadata at this point.
771
            && in_array($countryCallingCode, self::$GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES)
772
        ) {
773
            return 0;
774
        }
775
776
        if (!$this->isNumberGeographical($type, $countryCallingCode)) {
777
            return 0;
778
        }
779
780
        return $this->getLengthOfNationalDestinationCode($number);
781
    }
782
783
    /**
784
     * Returns the metadata for the given region code or {@code null} if the region code is invalid
785
     * or unknown.
786
     * @param string $regionCode
787
     * @return PhoneMetadata
788
     */
789
    public function getMetadataForRegion($regionCode)
790
    {
791
        if (!$this->isValidRegionCode($regionCode)) {
792
            return null;
793
        }
794
795
        return $this->metadataSource->getMetadataForRegion($regionCode);
796
    }
797
798
    /**
799
     * Helper function to check region code is not unknown or null.
800
     * @param string $regionCode
801
     * @return bool
802
     */
803
    protected function isValidRegionCode($regionCode)
804
    {
805
        return $regionCode !== null && in_array($regionCode, $this->supportedRegions);
806
    }
807
808
    /**
809
     * Returns the region where a phone number is from. This could be used for geocoding at the region
810
     * level.
811
     *
812
     * @param PhoneNumber $number the phone number whose origin we want to know
813
     * @return null|string  the region where the phone number is from, or null if no region matches this calling
814
     * code
815
     */
816
    public function getRegionCodeForNumber(PhoneNumber $number)
817
    {
818
        $countryCode = $number->getCountryCode();
819
        if (!isset($this->countryCallingCodeToRegionCodeMap[$countryCode])) {
820
            return null;
821
        }
822
        $regions = $this->countryCallingCodeToRegionCodeMap[$countryCode];
823
        if (count($regions) == 1) {
824
            return $regions[0];
825
        } else {
826
            return $this->getRegionCodeForNumberFromRegionList($number, $regions);
827
        }
828
    }
829
830
    /**
831
     * @param PhoneNumber $number
832
     * @param array $regionCodes
833
     * @return null|string
834
     */
835
    protected function getRegionCodeForNumberFromRegionList(PhoneNumber $number, array $regionCodes)
836
    {
837
        $nationalNumber = $this->getNationalSignificantNumber($number);
838
        foreach ($regionCodes as $regionCode) {
839
            // If leadingDigits is present, use this. Otherwise, do full validation.
840
            // Metadata cannot be null because the region codes come from the country calling code map.
841
            $metadata = $this->getMetadataForRegion($regionCode);
842
            if ($metadata->hasLeadingDigits()) {
843
                $nbMatches = preg_match(
844
                    '/' . $metadata->getLeadingDigits() . '/',
845
                    $nationalNumber,
846
                    $matches,
847
                    PREG_OFFSET_CAPTURE
848
                );
849
                if ($nbMatches > 0 && $matches[0][1] === 0) {
850
                    return $regionCode;
851
                }
852
            } elseif ($this->getNumberTypeHelper($nationalNumber, $metadata) != PhoneNumberType::UNKNOWN) {
0 ignored issues
show
Bug introduced by
It seems like $metadata defined by $this->getMetadataForRegion($regionCode) on line 841 can be null; however, libphonenumber\PhoneNumb...::getNumberTypeHelper() does not accept null, maybe add an additional type check?

Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code:

/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
853
                return $regionCode;
854
            }
855
        }
856
        return null;
857
    }
858
859
    /**
860
     * Gets the national significant number of the a phone number. Note a national significant number
861
     * doesn't contain a national prefix or any formatting.
862
     *
863
     * @param PhoneNumber $number the phone number for which the national significant number is needed
864
     * @return string the national significant number of the PhoneNumber object passed in
865
     */
866
    public function getNationalSignificantNumber(PhoneNumber $number)
867
    {
868
        // If leading zero(s) have been set, we prefix this now. Note this is not a national prefix.
869
        $nationalNumber = '';
870
        if ($number->isItalianLeadingZero() && $number->getNumberOfLeadingZeros() > 0) {
871
            $zeros = str_repeat('0', $number->getNumberOfLeadingZeros());
872
            $nationalNumber .= $zeros;
873
        }
874
        $nationalNumber .= $number->getNationalNumber();
875
        return $nationalNumber;
876
    }
877
878
    /**
879
     * @param string $nationalNumber
880
     * @param PhoneMetadata $metadata
881
     * @return int PhoneNumberType constant
882
     */
883
    protected function getNumberTypeHelper($nationalNumber, PhoneMetadata $metadata)
884
    {
885
        if (!$this->isNumberMatchingDesc($nationalNumber, $metadata->getGeneralDesc())) {
886
            return PhoneNumberType::UNKNOWN;
887
        }
888
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPremiumRate())) {
889
            return PhoneNumberType::PREMIUM_RATE;
890
        }
891
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getTollFree())) {
892
            return PhoneNumberType::TOLL_FREE;
893
        }
894
895
896
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getSharedCost())) {
897
            return PhoneNumberType::SHARED_COST;
898
        }
899
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getVoip())) {
900
            return PhoneNumberType::VOIP;
901
        }
902
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPersonalNumber())) {
903
            return PhoneNumberType::PERSONAL_NUMBER;
904
        }
905
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPager())) {
906
            return PhoneNumberType::PAGER;
907
        }
908
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getUan())) {
909
            return PhoneNumberType::UAN;
910
        }
911
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getVoicemail())) {
912
            return PhoneNumberType::VOICEMAIL;
913
        }
914
        $isFixedLine = $this->isNumberMatchingDesc($nationalNumber, $metadata->getFixedLine());
915
        if ($isFixedLine) {
916
            if ($metadata->isSameMobileAndFixedLinePattern()) {
917
                return PhoneNumberType::FIXED_LINE_OR_MOBILE;
918
            } elseif ($this->isNumberMatchingDesc($nationalNumber, $metadata->getMobile())) {
919
                return PhoneNumberType::FIXED_LINE_OR_MOBILE;
920
            }
921
            return PhoneNumberType::FIXED_LINE;
922
        }
923
        // Otherwise, test to see if the number is mobile. Only do this if certain that the patterns for
924
        // mobile and fixed line aren't the same.
925
        if (!$metadata->isSameMobileAndFixedLinePattern() &&
926
            $this->isNumberMatchingDesc($nationalNumber, $metadata->getMobile())
927
        ) {
928
            return PhoneNumberType::MOBILE;
929
        }
930
        return PhoneNumberType::UNKNOWN;
931
    }
932
933
    /**
934
     * @param string $nationalNumber
935
     * @param PhoneNumberDesc $numberDesc
936
     * @return bool
937
     */
938
    public function isNumberMatchingDesc($nationalNumber, PhoneNumberDesc $numberDesc)
939
    {
940
        // Check if any possible number lengths are present; if so, we use them to avoid checking the
941
        // validation pattern if they don't match. If they are absent, this means they match the general
942
        // description, which we have already checked before checking a specific number type.
943
        $actualLength = mb_strlen($nationalNumber);
944
        $possibleLengths = $numberDesc->getPossibleLength();
945
        if (count($possibleLengths) > 0 && !in_array($actualLength, $possibleLengths)) {
946
            return false;
947
        }
948
949
        $nationalNumberPatternMatcher = new Matcher($numberDesc->getNationalNumberPattern(), $nationalNumber);
950
951
        return $nationalNumberPatternMatcher->matches();
952
    }
953
954
    /**
955
     * isNumberGeographical(PhoneNumber)
956
     *
957
     * Tests whether a phone number has a geographical association. It checks if the number is
958
     * associated to a certain region in the country where it belongs to. Note that this doesn't
959
     * verify if the number is actually in use.
960
     *
961
     * isNumberGeographical(PhoneNumberType, $countryCallingCode)
962
     *
963
     * Tests whether a phone number has a geographical association, as represented by its type and the
964
     * country it belongs to.
965
     *
966
     * This version exists since calculating the phone number type is expensive; if we have already
967
     * done this, we don't want to do it again.
968
     *
969
     * @param PhoneNumber|int $phoneNumberObjOrType A PhoneNumber object, or a PhoneNumberType integer
970
     * @param int|null $countryCallingCode Used when passing a PhoneNumberType
971
     * @return bool
972
     */
973
    public function isNumberGeographical($phoneNumberObjOrType, $countryCallingCode = null)
974
    {
975
        if ($phoneNumberObjOrType instanceof PhoneNumber) {
976
            return $this->isNumberGeographical($this->getNumberType($phoneNumberObjOrType), $phoneNumberObjOrType->getCountryCode());
977
        }
978
979
        return $phoneNumberObjOrType == PhoneNumberType::FIXED_LINE
980
        || $phoneNumberObjOrType == PhoneNumberType::FIXED_LINE_OR_MOBILE
981
        || (in_array($countryCallingCode, static::$GEO_MOBILE_COUNTRIES)
982
            && $phoneNumberObjOrType == PhoneNumberType::MOBILE);
983
    }
984
985
    /**
986
     * Gets the type of a phone number.
987
     * @param PhoneNumber $number the number the phone number that we want to know the type
988
     * @return int PhoneNumberType the type of the phone number
989
     */
990
    public function getNumberType(PhoneNumber $number)
991
    {
992
        $regionCode = $this->getRegionCodeForNumber($number);
993
        $metadata = $this->getMetadataForRegionOrCallingCode($number->getCountryCode(), $regionCode);
994
        if ($metadata === null) {
995
            return PhoneNumberType::UNKNOWN;
996
        }
997
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
998
        return $this->getNumberTypeHelper($nationalSignificantNumber, $metadata);
999
    }
1000
1001
    /**
1002
     * @param int $countryCallingCode
1003
     * @param string $regionCode
1004
     * @return PhoneMetadata
1005
     */
1006
    protected function getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode)
1007
    {
1008
        return static::REGION_CODE_FOR_NON_GEO_ENTITY === $regionCode ?
1009
            $this->getMetadataForNonGeographicalRegion($countryCallingCode) : $this->getMetadataForRegion($regionCode);
1010
    }
1011
1012
    /**
1013
     * @param int $countryCallingCode
1014
     * @return PhoneMetadata
1015
     */
1016
    public function getMetadataForNonGeographicalRegion($countryCallingCode)
1017
    {
1018
        if (!isset($this->countryCallingCodeToRegionCodeMap[$countryCallingCode])) {
1019
            return null;
1020
        }
1021
        return $this->metadataSource->getMetadataForNonGeographicalRegion($countryCallingCode);
1022
    }
1023
1024
    /**
1025
     * Gets the length of the national destination code (NDC) from the PhoneNumber object passed in,
1026
     * so that clients could use it to split a national significant number into NDC and subscriber
1027
     * number. The NDC of a phone number is normally the first group of digit(s) right after the
1028
     * country calling code when the number is formatted in the international format, if there is a
1029
     * subscriber number part that follows. An example of how this could be used:
1030
     *
1031
     * <code>
1032
     * $phoneUtil = PhoneNumberUtil::getInstance();
1033
     * $number = $phoneUtil->parse("18002530000", "US");
1034
     * $nationalSignificantNumber = $phoneUtil->getNationalSignificantNumber($number);
1035
     *
1036
     * $nationalDestinationCodeLength = $phoneUtil->getLengthOfNationalDestinationCode($number);
1037
     * if ($nationalDestinationCodeLength > 0) {
1038
     *     $nationalDestinationCode = substr($nationalSignificantNumber, 0, $nationalDestinationCodeLength);
1039
     *     $subscriberNumber = substr($nationalSignificantNumber, $nationalDestinationCodeLength);
1040
     * } else {
1041
     *     $nationalDestinationCode = "";
1042
     *     $subscriberNumber = $nationalSignificantNumber;
1043
     * }
1044
     * </code>
1045
     *
1046
     * Refer to the unit tests to see the difference between this function and
1047
     * {@link #getLengthOfGeographicalAreaCode}.
1048
     *
1049
     * @param PhoneNumber $number the PhoneNumber object for which clients want to know the length of the NDC.
1050
     * @return int the length of NDC of the PhoneNumber object passed in.
1051
     */
1052
    public function getLengthOfNationalDestinationCode(PhoneNumber $number)
1053
    {
1054
        if ($number->hasExtension()) {
1055
            // We don't want to alter the proto given to us, but we don't want to include the extension
1056
            // when we format it, so we copy it and clear the extension here.
1057
            $copiedProto = new PhoneNumber();
1058
            $copiedProto->mergeFrom($number);
1059
            $copiedProto->clearExtension();
1060
        } else {
1061
            $copiedProto = clone $number;
1062
        }
1063
1064
        $nationalSignificantNumber = $this->format($copiedProto, PhoneNumberFormat::INTERNATIONAL);
1065
1066
        $numberGroups = preg_split('/' . static::NON_DIGITS_PATTERN . '/', $nationalSignificantNumber);
1067
1068
        // The pattern will start with "+COUNTRY_CODE " so the first group will always be the empty
1069
        // string (before the + symbol) and the second group will be the country calling code. The third
1070
        // group will be area code if it is not the last group.
1071
        if (count($numberGroups) <= 3) {
1072
            return 0;
1073
        }
1074
1075
        if ($this->getNumberType($number) == PhoneNumberType::MOBILE) {
1076
            // For example Argentinian mobile numbers, when formatted in the international format, are in
1077
            // the form of +54 9 NDC XXXX.... As a result, we take the length of the third group (NDC) and
1078
            // add the length of the second group (which is the mobile token), which also forms part of
1079
            // the national significant number. This assumes that the mobile token is always formatted
1080
            // separately from the rest of the phone number.
1081
1082
            $mobileToken = static::getCountryMobileToken($number->getCountryCode());
1083
            if ($mobileToken !== "") {
1084
                return mb_strlen($numberGroups[2]) + mb_strlen($numberGroups[3]);
1085
            }
1086
        }
1087
        return mb_strlen($numberGroups[2]);
1088
    }
1089
1090
    /**
1091
     * Formats a phone number in the specified format using default rules. Note that this does not
1092
     * promise to produce a phone number that the user can dial from where they are - although we do
1093
     * format in either 'national' or 'international' format depending on what the client asks for, we
1094
     * do not currently support a more abbreviated format, such as for users in the same "area" who
1095
     * could potentially dial the number without area code. Note that if the phone number has a
1096
     * country calling code of 0 or an otherwise invalid country calling code, we cannot work out
1097
     * which formatting rules to apply so we return the national significant number with no formatting
1098
     * applied.
1099
     *
1100
     * @param PhoneNumber $number the phone number to be formatted
1101
     * @param int $numberFormat the PhoneNumberFormat the phone number should be formatted into
1102
     * @return string the formatted phone number
1103
     */
1104
    public function format(PhoneNumber $number, $numberFormat)
1105
    {
1106
        if ($number->getNationalNumber() == 0 && $number->hasRawInput()) {
1107
            // Unparseable numbers that kept their raw input just use that.
1108
            // This is the only case where a number can be formatted as E164 without a
1109
            // leading '+' symbol (but the original number wasn't parseable anyway).
1110
            // TODO: Consider removing the 'if' above so that unparseable
1111
            // strings without raw input format to the empty string instead of "+00"
1112
            $rawInput = $number->getRawInput();
1113
            if (mb_strlen($rawInput) > 0) {
1114
                return $rawInput;
1115
            }
1116
        }
1117
1118
        $formattedNumber = "";
1119
        $countryCallingCode = $number->getCountryCode();
1120
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
1121
1122
        if ($numberFormat == PhoneNumberFormat::E164) {
1123
            // Early exit for E164 case (even if the country calling code is invalid) since no formatting
1124
            // of the national number needs to be applied. Extensions are not formatted.
1125
            $formattedNumber .= $nationalSignificantNumber;
1126
            $this->prefixNumberWithCountryCallingCode($countryCallingCode, PhoneNumberFormat::E164, $formattedNumber);
1127
            return $formattedNumber;
1128
        }
1129
1130
        if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
1131
            $formattedNumber .= $nationalSignificantNumber;
1132
            return $formattedNumber;
1133
        }
1134
1135
        // Note getRegionCodeForCountryCode() is used because formatting information for regions which
1136
        // share a country calling code is contained by only one region for performance reasons. For
1137
        // example, for NANPA regions it will be contained in the metadata for US.
1138
        $regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
1139
        // Metadata cannot be null because the country calling code is valid (which means that the
1140
        // region code cannot be ZZ and must be one of our supported region codes).
1141
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode);
1142
        $formattedNumber .= $this->formatNsn($nationalSignificantNumber, $metadata, $numberFormat);
0 ignored issues
show
Bug introduced by
It seems like $metadata defined by $this->getMetadataForReg...llingCode, $regionCode) on line 1141 can be null; however, libphonenumber\PhoneNumberUtil::formatNsn() does not accept null, maybe add an additional type check?

Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code:

/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
1143
        $this->maybeAppendFormattedExtension($number, $metadata, $numberFormat, $formattedNumber);
1144
        $this->prefixNumberWithCountryCallingCode($countryCallingCode, $numberFormat, $formattedNumber);
1145
        return $formattedNumber;
1146
    }
1147
1148
    /**
1149
     * A helper function that is used by format and formatByPattern.
1150
     * @param int $countryCallingCode
1151
     * @param int $numberFormat PhoneNumberFormat
1152
     * @param string $formattedNumber
1153
     */
1154
    protected function prefixNumberWithCountryCallingCode($countryCallingCode, $numberFormat, &$formattedNumber)
1155
    {
1156
        switch ($numberFormat) {
1157
            case PhoneNumberFormat::E164:
1158
                $formattedNumber = static::PLUS_SIGN . $countryCallingCode . $formattedNumber;
1159
                return;
1160
            case PhoneNumberFormat::INTERNATIONAL:
1161
                $formattedNumber = static::PLUS_SIGN . $countryCallingCode . " " . $formattedNumber;
1162
                return;
1163
            case PhoneNumberFormat::RFC3966:
1164
                $formattedNumber = static::RFC3966_PREFIX . static::PLUS_SIGN . $countryCallingCode . "-" . $formattedNumber;
1165
                return;
1166
            case PhoneNumberFormat::NATIONAL:
1167
            default:
1168
                return;
1169
        }
1170
    }
1171
1172
    /**
1173
     * Helper function to check the country calling code is valid.
1174
     * @param int $countryCallingCode
1175
     * @return bool
1176
     */
1177
    protected function hasValidCountryCallingCode($countryCallingCode)
1178
    {
1179
        return isset($this->countryCallingCodeToRegionCodeMap[$countryCallingCode]);
1180
    }
1181
1182
    /**
1183
     * Returns the region code that matches the specific country calling code. In the case of no
1184
     * region code being found, ZZ will be returned. In the case of multiple regions, the one
1185
     * designated in the metadata as the "main" region for this calling code will be returned. If the
1186
     * countryCallingCode entered is valid but doesn't match a specific region (such as in the case of
1187
     * non-geographical calling codes like 800) the value "001" will be returned (corresponding to
1188
     * the value for World in the UN M.49 schema).
1189
     *
1190
     * @param int $countryCallingCode
1191
     * @return string
1192
     */
1193
    public function getRegionCodeForCountryCode($countryCallingCode)
1194
    {
1195
        $regionCodes = isset($this->countryCallingCodeToRegionCodeMap[$countryCallingCode]) ? $this->countryCallingCodeToRegionCodeMap[$countryCallingCode] : null;
1196
        return $regionCodes === null ? static::UNKNOWN_REGION : $regionCodes[0];
1197
    }
1198
1199
    /**
1200
     * Note in some regions, the national number can be written in two completely different ways
1201
     * depending on whether it forms part of the NATIONAL format or INTERNATIONAL format. The
1202
     * numberFormat parameter here is used to specify which format to use for those cases. If a
1203
     * carrierCode is specified, this will be inserted into the formatted string to replace $CC.
1204
     * @param string $number
1205
     * @param PhoneMetadata $metadata
1206
     * @param int $numberFormat PhoneNumberFormat
1207
     * @param null|string $carrierCode
1208
     * @return string
1209
     */
1210
    protected function formatNsn($number, PhoneMetadata $metadata, $numberFormat, $carrierCode = null)
1211
    {
1212
        $intlNumberFormats = $metadata->intlNumberFormats();
1213
        // When the intlNumberFormats exists, we use that to format national number for the
1214
        // INTERNATIONAL format instead of using the numberDesc.numberFormats.
1215
        $availableFormats = (count($intlNumberFormats) == 0 || $numberFormat == PhoneNumberFormat::NATIONAL)
1216
            ? $metadata->numberFormats()
1217
            : $metadata->intlNumberFormats();
1218
        $formattingPattern = $this->chooseFormattingPatternForNumber($availableFormats, $number);
1219
        return ($formattingPattern === null)
1220
            ? $number
1221
            : $this->formatNsnUsingPattern($number, $formattingPattern, $numberFormat, $carrierCode);
1222
    }
1223
1224
    /**
1225
     * @param NumberFormat[] $availableFormats
1226
     * @param string $nationalNumber
1227
     * @return NumberFormat|null
1228
     */
1229
    public function chooseFormattingPatternForNumber(array $availableFormats, $nationalNumber)
1230
    {
1231
        foreach ($availableFormats as $numFormat) {
1232
            $leadingDigitsPatternMatcher = null;
1233
            $size = $numFormat->leadingDigitsPatternSize();
1234
            // We always use the last leading_digits_pattern, as it is the most detailed.
1235
            if ($size > 0) {
1236
                $leadingDigitsPatternMatcher = new Matcher(
1237
                    $numFormat->getLeadingDigitsPattern($size - 1),
1238
                    $nationalNumber
1239
                );
1240
            }
1241
            if ($size == 0 || $leadingDigitsPatternMatcher->lookingAt()) {
1242
                $m = new Matcher($numFormat->getPattern(), $nationalNumber);
1243
                if ($m->matches() > 0) {
1244
                    return $numFormat;
1245
                }
1246
            }
1247
        }
1248
        return null;
1249
    }
1250
1251
    /**
1252
     * Note that carrierCode is optional - if null or an empty string, no carrier code replacement
1253
     * will take place.
1254
     * @param string $nationalNumber
1255
     * @param NumberFormat $formattingPattern
1256
     * @param int $numberFormat PhoneNumberFormat
1257
     * @param null|string $carrierCode
1258
     * @return string
1259
     */
1260
    public function formatNsnUsingPattern(
1261
        $nationalNumber,
1262
        NumberFormat $formattingPattern,
1263
        $numberFormat,
1264
        $carrierCode = null
1265
    ) {
1266
        $numberFormatRule = $formattingPattern->getFormat();
1267
        $m = new Matcher($formattingPattern->getPattern(), $nationalNumber);
1268
        if ($numberFormat === PhoneNumberFormat::NATIONAL &&
1269
            $carrierCode !== null && mb_strlen($carrierCode) > 0 &&
1270
            mb_strlen($formattingPattern->getDomesticCarrierCodeFormattingRule()) > 0
1271
        ) {
1272
            // Replace the $CC in the formatting rule with the desired carrier code.
1273
            $carrierCodeFormattingRule = $formattingPattern->getDomesticCarrierCodeFormattingRule();
1274
            $ccPatternMatcher = new Matcher(static::CC_PATTERN, $carrierCodeFormattingRule);
1275
            $carrierCodeFormattingRule = $ccPatternMatcher->replaceFirst($carrierCode);
1276
            // Now replace the $FG in the formatting rule with the first group and the carrier code
1277
            // combined in the appropriate way.
1278
            $firstGroupMatcher = new Matcher(static::FIRST_GROUP_PATTERN, $numberFormatRule);
1279
            $numberFormatRule = $firstGroupMatcher->replaceFirst($carrierCodeFormattingRule);
1280
            $formattedNationalNumber = $m->replaceAll($numberFormatRule);
1281
        } else {
1282
            // Use the national prefix formatting rule instead.
1283
            $nationalPrefixFormattingRule = $formattingPattern->getNationalPrefixFormattingRule();
1284
            if ($numberFormat == PhoneNumberFormat::NATIONAL &&
1285
                $nationalPrefixFormattingRule !== null &&
1286
                mb_strlen($nationalPrefixFormattingRule) > 0
1287
            ) {
1288
                $firstGroupMatcher = new Matcher(static::FIRST_GROUP_PATTERN, $numberFormatRule);
1289
                $formattedNationalNumber = $m->replaceAll(
1290
                    $firstGroupMatcher->replaceFirst($nationalPrefixFormattingRule)
1291
                );
1292
            } else {
1293
                $formattedNationalNumber = $m->replaceAll($numberFormatRule);
1294
            }
1295
        }
1296
        if ($numberFormat == PhoneNumberFormat::RFC3966) {
1297
            // Strip any leading punctuation.
1298
            $matcher = new Matcher(static::$SEPARATOR_PATTERN, $formattedNationalNumber);
1299
            if ($matcher->lookingAt()) {
1300
                $formattedNationalNumber = $matcher->replaceFirst("");
1301
            }
1302
            // Replace the rest with a dash between each number group.
1303
            $formattedNationalNumber = $matcher->reset($formattedNationalNumber)->replaceAll("-");
1304
        }
1305
        return $formattedNationalNumber;
1306
    }
1307
1308
    /**
1309
     * Appends the formatted extension of a phone number to formattedNumber, if the phone number had
1310
     * an extension specified.
1311
     *
1312
     * @param PhoneNumber $number
1313
     * @param PhoneMetadata|null $metadata
1314
     * @param int $numberFormat PhoneNumberFormat
1315
     * @param string $formattedNumber
1316
     */
1317
    protected function maybeAppendFormattedExtension(PhoneNumber $number, $metadata, $numberFormat, &$formattedNumber)
1318
    {
1319
        if ($number->hasExtension() && mb_strlen($number->getExtension()) > 0) {
1320
            if ($numberFormat === PhoneNumberFormat::RFC3966) {
1321
                $formattedNumber .= static::RFC3966_EXTN_PREFIX . $number->getExtension();
1322
            } else {
1323
                if (!empty($metadata) && $metadata->hasPreferredExtnPrefix()) {
1324
                    $formattedNumber .= $metadata->getPreferredExtnPrefix() . $number->getExtension();
1325
                } else {
1326
                    $formattedNumber .= static::DEFAULT_EXTN_PREFIX . $number->getExtension();
1327
                }
1328
            }
1329
        }
1330
    }
1331
1332
    /**
1333
     * Returns the mobile token for the provided country calling code if it has one, otherwise
1334
     * returns an empty string. A mobile token is a number inserted before the area code when dialing
1335
     * a mobile number from that country from abroad.
1336
     *
1337
     * @param int $countryCallingCode the country calling code for which we want the mobile token
1338
     * @return string the mobile token, as a string, for the given country calling code
1339
     */
1340
    public static function getCountryMobileToken($countryCallingCode)
1341
    {
1342
        if (count(static::$MOBILE_TOKEN_MAPPINGS) === 0) {
1343
            static::initMobileTokenMappings();
1344
        }
1345
1346
        if (array_key_exists($countryCallingCode, static::$MOBILE_TOKEN_MAPPINGS)) {
1347
            return static::$MOBILE_TOKEN_MAPPINGS[$countryCallingCode];
1348
        }
1349
        return "";
1350
    }
1351
1352
    /**
1353
     * Checks if the number is a valid vanity (alpha) number such as 800 MICROSOFT. A valid vanity
1354
     * number will start with at least 3 digits and will have three or more alpha characters. This
1355
     * does not do region-specific checks - to work out if this number is actually valid for a region,
1356
     * it should be parsed and methods such as {@link #isPossibleNumberWithReason} and
1357
     * {@link #isValidNumber} should be used.
1358
     *
1359
     * @param string $number the number that needs to be checked
1360
     * @return bool true if the number is a valid vanity number
1361
     */
1362
    public function isAlphaNumber($number)
1363
    {
1364
        if (!static::isViablePhoneNumber($number)) {
1365
            // Number is too short, or doesn't match the basic phone number pattern.
1366
            return false;
1367
        }
1368
        $this->maybeStripExtension($number);
1369
        return (bool)preg_match('/' . static::VALID_ALPHA_PHONE_PATTERN . '/' . static::REGEX_FLAGS, $number);
1370
    }
1371
1372
    /**
1373
     * Checks to see if the string of characters could possibly be a phone number at all. At the
1374
     * moment, checks to see that the string begins with at least 2 digits, ignoring any punctuation
1375
     * commonly found in phone numbers.
1376
     * This method does not require the number to be normalized in advance - but does assume that
1377
     * leading non-number symbols have been removed, such as by the method extractPossibleNumber.
1378
     *
1379
     * @param string $number to be checked for viability as a phone number
1380
     * @return boolean true if the number could be a phone number of some sort, otherwise false
1381
     */
1382
    public static function isViablePhoneNumber($number)
1383
    {
1384
        if (static::$VALID_PHONE_NUMBER_PATTERN === null) {
1385
            static::initValidPhoneNumberPatterns();
1386
        }
1387
1388
        if (mb_strlen($number) < static::MIN_LENGTH_FOR_NSN) {
1389
            return false;
1390
        }
1391
1392
        $validPhoneNumberPattern = static::getValidPhoneNumberPattern();
1393
1394
        $m = preg_match($validPhoneNumberPattern, $number);
1395
        return $m > 0;
1396
    }
1397
1398
    /**
1399
     * We append optionally the extension pattern to the end here, as a valid phone number may
1400
     * have an extension prefix appended, followed by 1 or more digits.
1401
     * @return string
1402
     */
1403
    protected static function getValidPhoneNumberPattern()
1404
    {
1405
        return static::$VALID_PHONE_NUMBER_PATTERN;
1406
    }
1407
1408
    /**
1409
     * Strips any extension (as in, the part of the number dialled after the call is connected,
1410
     * usually indicated with extn, ext, x or similar) from the end of the number, and returns it.
1411
     *
1412
     * @param string $number the non-normalized telephone number that we wish to strip the extension from
1413
     * @return string the phone extension
1414
     */
1415
    protected function maybeStripExtension(&$number)
1416
    {
1417
        $matches = array();
1418
        $find = preg_match(static::$EXTN_PATTERN, $number, $matches, PREG_OFFSET_CAPTURE);
1419
        // If we find a potential extension, and the number preceding this is a viable number, we assume
1420
        // it is an extension.
1421
        if ($find > 0 && static::isViablePhoneNumber(substr($number, 0, $matches[0][1]))) {
1422
            // The numbers are captured into groups in the regular expression.
1423
1424
            for ($i = 1, $length = count($matches); $i <= $length; $i++) {
1425
                if ($matches[$i][0] != "") {
1426
                    // We go through the capturing groups until we find one that captured some digits. If none
1427
                    // did, then we will return the empty string.
1428
                    $extension = $matches[$i][0];
1429
                    $number = substr($number, 0, $matches[0][1]);
1430
                    return $extension;
1431
                }
1432
            }
1433
        }
1434
        return "";
1435
    }
1436
1437
    /**
1438
     * Parses a string and returns it in proto buffer format. This method differs from {@link #parse}
1439
     * in that it always populates the raw_input field of the protocol buffer with numberToParse as
1440
     * well as the country_code_source field.
1441
     *
1442
     * @param string $numberToParse number that we are attempting to parse. This can contain formatting
1443
     *                                  such as +, ( and -, as well as a phone number extension. It can also
1444
     *                                  be provided in RFC3966 format.
1445
     * @param string $defaultRegion region that we are expecting the number to be from. This is only used
1446
     *                                  if the number being parsed is not written in international format.
1447
     *                                  The country calling code for the number in this case would be stored
1448
     *                                  as that of the default region supplied.
1449
     * @param PhoneNumber $phoneNumber
1450
     * @return PhoneNumber              a phone number proto buffer filled with the parsed number
1451
     */
1452
    public function parseAndKeepRawInput($numberToParse, $defaultRegion, PhoneNumber $phoneNumber = null)
1453
    {
1454
        if ($phoneNumber === null) {
1455
            $phoneNumber = new PhoneNumber();
1456
        }
1457
        $this->parseHelper($numberToParse, $defaultRegion, true, true, $phoneNumber);
1458
        return $phoneNumber;
1459
    }
1460
1461
    /**
1462
     * Returns an iterable over all PhoneNumberMatches in $text
1463
     *
1464
     * @param string $text
1465
     * @param string $defaultRegion
1466
     * @param AbstractLeniency $leniency Defaults to Leniency::VALID()
1467
     * @param int $maxTries Defaults to PHP_INT_MAX
1468
     * @return PhoneNumberMatcher
1469
     */
1470
    public function findNumbers($text, $defaultRegion, AbstractLeniency $leniency = null, $maxTries = PHP_INT_MAX)
1471
    {
1472
        if ($leniency === null) {
1473
            $leniency = Leniency::VALID();
1474
        }
1475
1476
        return new PhoneNumberMatcher($this, $text, $defaultRegion, $leniency, $maxTries);
1477
    }
1478
1479
    /**
1480
     * Gets an AsYouTypeFormatter for the specific region.
1481
     *
1482
     * @param string $regionCode The region where the phone number is being entered.
1483
     * @return AsYouTypeFormatter
1484
     */
1485
    public function getAsYouTypeFormatter($regionCode)
1486
    {
1487
        return new AsYouTypeFormatter($regionCode);
1488
    }
1489
1490
    /**
1491
     * A helper function to set the values related to leading zeros in a PhoneNumber.
1492
     * @param string $nationalNumber
1493
     * @param PhoneNumber $phoneNumber
1494
     */
1495
    public static function setItalianLeadingZerosForPhoneNumber($nationalNumber, PhoneNumber $phoneNumber)
1496
    {
1497
        if (strlen($nationalNumber) > 1 && substr($nationalNumber, 0, 1) == '0') {
1498
            $phoneNumber->setItalianLeadingZero(true);
1499
            $numberOfLeadingZeros = 1;
1500
            // Note that if the national number is all "0"s, the last "0" is not counted as a leading
1501
            // zero.
1502
            while ($numberOfLeadingZeros < (strlen($nationalNumber) - 1) &&
1503
                substr($nationalNumber, $numberOfLeadingZeros, 1) == '0') {
1504
                $numberOfLeadingZeros++;
1505
            }
1506
1507
            if ($numberOfLeadingZeros != 1) {
1508
                $phoneNumber->setNumberOfLeadingZeros($numberOfLeadingZeros);
1509
            }
1510
        }
1511
    }
1512
1513
    /**
1514
     * Parses a string and fills up the phoneNumber. This method is the same as the public
1515
     * parse() method, with the exception that it allows the default region to be null, for use by
1516
     * isNumberMatch(). checkRegion should be set to false if it is permitted for the default region
1517
     * to be null or unknown ("ZZ").
1518
     * @param string $numberToParse
1519
     * @param string $defaultRegion
1520
     * @param bool $keepRawInput
1521
     * @param bool $checkRegion
1522
     * @param PhoneNumber $phoneNumber
1523
     * @throws NumberParseException
1524
     */
1525
    protected function parseHelper($numberToParse, $defaultRegion, $keepRawInput, $checkRegion, PhoneNumber $phoneNumber)
1526
    {
1527
        if ($numberToParse === null) {
1528
            throw new NumberParseException(NumberParseException::NOT_A_NUMBER, "The phone number supplied was null.");
1529
        }
1530
1531
        $numberToParse = trim($numberToParse);
1532
1533
        if (mb_strlen($numberToParse) > static::MAX_INPUT_STRING_LENGTH) {
1534
            throw new NumberParseException(
1535
                NumberParseException::TOO_LONG,
1536
                "The string supplied was too long to parse."
1537
            );
1538
        }
1539
1540
        $nationalNumber = '';
1541
        $this->buildNationalNumberForParsing($numberToParse, $nationalNumber);
1542
1543
        if (!static::isViablePhoneNumber($nationalNumber)) {
1544
            throw new NumberParseException(
1545
                NumberParseException::NOT_A_NUMBER,
1546
                "The string supplied did not seem to be a phone number."
1547
            );
1548
        }
1549
1550
        // Check the region supplied is valid, or that the extracted number starts with some sort of +
1551
        // sign so the number's region can be determined.
1552
        if ($checkRegion && !$this->checkRegionForParsing($nationalNumber, $defaultRegion)) {
1553
            throw new NumberParseException(
1554
                NumberParseException::INVALID_COUNTRY_CODE,
1555
                "Missing or invalid default region."
1556
            );
1557
        }
1558
1559
        if ($keepRawInput) {
1560
            $phoneNumber->setRawInput($numberToParse);
1561
        }
1562
        // Attempt to parse extension first, since it doesn't require region-specific data and we want
1563
        // to have the non-normalised number here.
1564
        $extension = $this->maybeStripExtension($nationalNumber);
1565
        if (mb_strlen($extension) > 0) {
1566
            $phoneNumber->setExtension($extension);
1567
        }
1568
1569
        $regionMetadata = $this->getMetadataForRegion($defaultRegion);
1570
        // Check to see if the number is given in international format so we know whether this number is
1571
        // from the default region or not.
1572
        $normalizedNationalNumber = "";
1573
        try {
1574
            // TODO: This method should really just take in the string buffer that has already
1575
            // been created, and just remove the prefix, rather than taking in a string and then
1576
            // outputting a string buffer.
1577
            $countryCode = $this->maybeExtractCountryCode(
1578
                $nationalNumber,
1579
                $regionMetadata,
1580
                $normalizedNationalNumber,
1581
                $keepRawInput,
1582
                $phoneNumber
1583
            );
1584
        } catch (NumberParseException $e) {
1585
            $matcher = new Matcher(static::$PLUS_CHARS_PATTERN, $nationalNumber);
1586
            if ($e->getErrorType() == NumberParseException::INVALID_COUNTRY_CODE && $matcher->lookingAt()) {
1587
                // Strip the plus-char, and try again.
1588
                $countryCode = $this->maybeExtractCountryCode(
1589
                    substr($nationalNumber, $matcher->end()),
1590
                    $regionMetadata,
1591
                    $normalizedNationalNumber,
1592
                    $keepRawInput,
1593
                    $phoneNumber
1594
                );
1595
                if ($countryCode == 0) {
1596
                    throw new NumberParseException(
1597
                        NumberParseException::INVALID_COUNTRY_CODE,
1598
                        "Could not interpret numbers after plus-sign."
1599
                    );
1600
                }
1601
            } else {
1602
                throw new NumberParseException($e->getErrorType(), $e->getMessage(), $e);
1603
            }
1604
        }
1605
        if ($countryCode !== 0) {
1606
            $phoneNumberRegion = $this->getRegionCodeForCountryCode($countryCode);
1607
            if ($phoneNumberRegion != $defaultRegion) {
1608
                // Metadata cannot be null because the country calling code is valid.
1609
                $regionMetadata = $this->getMetadataForRegionOrCallingCode($countryCode, $phoneNumberRegion);
1610
            }
1611
        } else {
1612
            // If no extracted country calling code, use the region supplied instead. The national number
1613
            // is just the normalized version of the number we were given to parse.
1614
1615
            $normalizedNationalNumber .= static::normalize($nationalNumber);
1616
            if ($defaultRegion !== null) {
1617
                $countryCode = $regionMetadata->getCountryCode();
1618
                $phoneNumber->setCountryCode($countryCode);
1619
            } elseif ($keepRawInput) {
1620
                $phoneNumber->clearCountryCodeSource();
1621
            }
1622
        }
1623
        if (mb_strlen($normalizedNationalNumber) < static::MIN_LENGTH_FOR_NSN) {
1624
            throw new NumberParseException(
1625
                NumberParseException::TOO_SHORT_NSN,
1626
                "The string supplied is too short to be a phone number."
1627
            );
1628
        }
1629
        if ($regionMetadata !== null) {
1630
            $carrierCode = "";
1631
            $potentialNationalNumber = $normalizedNationalNumber;
1632
            $this->maybeStripNationalPrefixAndCarrierCode($potentialNationalNumber, $regionMetadata, $carrierCode);
1633
            // We require that the NSN remaining after stripping the national prefix and carrier code be
1634
            // long enough to be a possible length for the region. Otherwise, we don't do the stripping,
1635
            // since the original number could be a valid short number.
1636
            if ($this->testNumberLength($potentialNationalNumber, $regionMetadata) !== ValidationResult::TOO_SHORT) {
1637
                $normalizedNationalNumber = $potentialNationalNumber;
1638
                if ($keepRawInput && mb_strlen($carrierCode) > 0) {
1639
                    $phoneNumber->setPreferredDomesticCarrierCode($carrierCode);
1640
                }
1641
            }
1642
        }
1643
        $lengthOfNationalNumber = mb_strlen($normalizedNationalNumber);
1644
        if ($lengthOfNationalNumber < static::MIN_LENGTH_FOR_NSN) {
1645
            throw new NumberParseException(
1646
                NumberParseException::TOO_SHORT_NSN,
1647
                "The string supplied is too short to be a phone number."
1648
            );
1649
        }
1650
        if ($lengthOfNationalNumber > static::MAX_LENGTH_FOR_NSN) {
1651
            throw new NumberParseException(
1652
                NumberParseException::TOO_LONG,
1653
                "The string supplied is too long to be a phone number."
1654
            );
1655
        }
1656
        static::setItalianLeadingZerosForPhoneNumber($normalizedNationalNumber, $phoneNumber);
1657
1658
        /*
1659
         * We have to store the National Number as a string instead of a "long" as Google do
1660
         *
1661
         * Since PHP doesn't always support 64 bit INTs, this was a float, but that had issues
1662
         * with long numbers.
1663
         *
1664
         * We have to remove the leading zeroes ourself though
1665
         */
1666
        if ((int)$normalizedNationalNumber == 0) {
1667
            $normalizedNationalNumber = "0";
1668
        } else {
1669
            $normalizedNationalNumber = ltrim($normalizedNationalNumber, '0');
1670
        }
1671
1672
        $phoneNumber->setNationalNumber($normalizedNationalNumber);
1673
    }
1674
1675
    /**
1676
     * Returns a new phone number containing only the fields needed to uniquely identify a phone
1677
     * number, rather than any fields that capture the context in which  the phone number was created.
1678
     * These fields correspond to those set in parse() rather than parseAndKeepRawInput()
1679
     *
1680
     * @param PhoneNumber $phoneNumberIn
1681
     * @return PhoneNumber
1682
     */
1683
    protected static function copyCoreFieldsOnly(PhoneNumber $phoneNumberIn)
1684
    {
1685
        $phoneNumber = new PhoneNumber();
1686
        $phoneNumber->setCountryCode($phoneNumberIn->getCountryCode());
1687
        $phoneNumber->setNationalNumber($phoneNumberIn->getNationalNumber());
1688
        if (mb_strlen($phoneNumberIn->getExtension()) > 0) {
1689
            $phoneNumber->setExtension($phoneNumberIn->getExtension());
1690
        }
1691
        if ($phoneNumberIn->isItalianLeadingZero()) {
1692
            $phoneNumber->setItalianLeadingZero(true);
1693
            // This field is only relevant if there are leading zeros at all.
1694
            $phoneNumber->setNumberOfLeadingZeros($phoneNumberIn->getNumberOfLeadingZeros());
1695
        }
1696
        return $phoneNumber;
1697
    }
1698
1699
    /**
1700
     * Converts numberToParse to a form that we can parse and write it to nationalNumber if it is
1701
     * written in RFC3966; otherwise extract a possible number out of it and write to nationalNumber.
1702
     * @param string $numberToParse
1703
     * @param string $nationalNumber
1704
     */
1705
    protected function buildNationalNumberForParsing($numberToParse, &$nationalNumber)
1706
    {
1707
        $indexOfPhoneContext = strpos($numberToParse, static::RFC3966_PHONE_CONTEXT);
1708
        if ($indexOfPhoneContext > 0) {
1709
            $phoneContextStart = $indexOfPhoneContext + mb_strlen(static::RFC3966_PHONE_CONTEXT);
1710
            // If the phone context contains a phone number prefix, we need to capture it, whereas domains
1711
            // will be ignored.
1712
            if (substr($numberToParse, $phoneContextStart, 1) == static::PLUS_SIGN) {
1713
                // Additional parameters might follow the phone context. If so, we will remove them here
1714
                // because the parameters after phone context are not important for parsing the
1715
                // phone number.
1716
                $phoneContextEnd = strpos($numberToParse, ';', $phoneContextStart);
1717
                if ($phoneContextEnd > 0) {
1718
                    $nationalNumber .= substr($numberToParse, $phoneContextStart, $phoneContextEnd - $phoneContextStart);
1719
                } else {
1720
                    $nationalNumber .= substr($numberToParse, $phoneContextStart);
1721
                }
1722
            }
1723
1724
            // Now append everything between the "tel:" prefix and the phone-context. This should include
1725
            // the national number, an optional extension or isdn-subaddress component. Note we also
1726
            // handle the case when "tel:" is missing, as we have seen in some of the phone number inputs.
1727
            // In that case, we append everything from the beginning.
1728
1729
            $indexOfRfc3966Prefix = strpos($numberToParse, static::RFC3966_PREFIX);
1730
            $indexOfNationalNumber = ($indexOfRfc3966Prefix !== false) ? $indexOfRfc3966Prefix + strlen(static::RFC3966_PREFIX) : 0;
1731
            $nationalNumber .= substr($numberToParse, $indexOfNationalNumber, ($indexOfPhoneContext - $indexOfNationalNumber));
1732
        } else {
1733
            // Extract a possible number from the string passed in (this strips leading characters that
1734
            // could not be the start of a phone number.)
1735
            $nationalNumber .= static::extractPossibleNumber($numberToParse);
1736
        }
1737
1738
        // Delete the isdn-subaddress and everything after it if it is present. Note extension won't
1739
        // appear at the same time with isdn-subaddress according to paragraph 5.3 of the RFC3966 spec,
1740
        $indexOfIsdn = strpos($nationalNumber, static::RFC3966_ISDN_SUBADDRESS);
1741
        if ($indexOfIsdn > 0) {
1742
            $nationalNumber = substr($nationalNumber, 0, $indexOfIsdn);
1743
        }
1744
        // If both phone context and isdn-subaddress are absent but other parameters are present, the
1745
        // parameters are left in nationalNumber. This is because we are concerned about deleting
1746
        // content from a potential number string when there is no strong evidence that the number is
1747
        // actually written in RFC3966.
1748
    }
1749
1750
    /**
1751
     * Attempts to extract a possible number from the string passed in. This currently strips all
1752
     * leading characters that cannot be used to start a phone number. Characters that can be used to
1753
     * start a phone number are defined in the VALID_START_CHAR_PATTERN. If none of these characters
1754
     * are found in the number passed in, an empty string is returned. This function also attempts to
1755
     * strip off any alternative extensions or endings if two or more are present, such as in the case
1756
     * of: (530) 583-6985 x302/x2303. The second extension here makes this actually two phone numbers,
1757
     * (530) 583-6985 x302 and (530) 583-6985 x2303. We remove the second extension so that the first
1758
     * number is parsed correctly.
1759
     *
1760
     * @param int $number the string that might contain a phone number
1761
     * @return string the number, stripped of any non-phone-number prefix (such as "Tel:") or an empty
1762
     *                string if no character used to start phone numbers (such as + or any digit) is
1763
     *                found in the number
1764
     */
1765
    public static function extractPossibleNumber($number)
1766
    {
1767
        if (static::$VALID_START_CHAR_PATTERN === null) {
1768
            static::initValidStartCharPattern();
1769
        }
1770
1771
        $matches = array();
1772
        $match = preg_match('/' . static::$VALID_START_CHAR_PATTERN . '/ui', $number, $matches, PREG_OFFSET_CAPTURE);
1773
        if ($match > 0) {
1774
            $number = substr($number, $matches[0][1]);
1775
            // Remove trailing non-alpha non-numerical characters.
1776
            $trailingCharsMatcher = new Matcher(static::$UNWANTED_END_CHAR_PATTERN, $number);
1777
            if ($trailingCharsMatcher->find() && $trailingCharsMatcher->start() > 0) {
1778
                $number = substr($number, 0, $trailingCharsMatcher->start());
1779
            }
1780
1781
            // Check for extra numbers at the end.
1782
            $match = preg_match('%' . static::$SECOND_NUMBER_START_PATTERN . '%', $number, $matches, PREG_OFFSET_CAPTURE);
1783
            if ($match > 0) {
1784
                $number = substr($number, 0, $matches[0][1]);
1785
            }
1786
1787
            return $number;
1788
        } else {
1789
            return "";
1790
        }
1791
    }
1792
1793
    /**
1794
     * Checks to see that the region code used is valid, or if it is not valid, that the number to
1795
     * parse starts with a + symbol so that we can attempt to infer the region from the number.
1796
     * Returns false if it cannot use the region provided and the region cannot be inferred.
1797
     * @param string $numberToParse
1798
     * @param string $defaultRegion
1799
     * @return bool
1800
     */
1801
    protected function checkRegionForParsing($numberToParse, $defaultRegion)
1802
    {
1803
        if (!$this->isValidRegionCode($defaultRegion)) {
1804
            // If the number is null or empty, we can't infer the region.
1805
            $plusCharsPatternMatcher = new Matcher(static::$PLUS_CHARS_PATTERN, $numberToParse);
1806
            if ($numberToParse === null || mb_strlen($numberToParse) == 0 || !$plusCharsPatternMatcher->lookingAt()) {
1807
                return false;
1808
            }
1809
        }
1810
        return true;
1811
    }
1812
1813
    /**
1814
     * Tries to extract a country calling code from a number. This method will return zero if no
1815
     * country calling code is considered to be present. Country calling codes are extracted in the
1816
     * following ways:
1817
     * <ul>
1818
     *  <li> by stripping the international dialing prefix of the region the person is dialing from,
1819
     *       if this is present in the number, and looking at the next digits
1820
     *  <li> by stripping the '+' sign if present and then looking at the next digits
1821
     *  <li> by comparing the start of the number and the country calling code of the default region.
1822
     *       If the number is not considered possible for the numbering plan of the default region
1823
     *       initially, but starts with the country calling code of this region, validation will be
1824
     *       reattempted after stripping this country calling code. If this number is considered a
1825
     *       possible number, then the first digits will be considered the country calling code and
1826
     *       removed as such.
1827
     * </ul>
1828
     * It will throw a NumberParseException if the number starts with a '+' but the country calling
1829
     * code supplied after this does not match that of any known region.
1830
     *
1831
     * @param string $number non-normalized telephone number that we wish to extract a country calling
1832
     *     code from - may begin with '+'
1833
     * @param PhoneMetadata $defaultRegionMetadata metadata about the region this number may be from
1834
     * @param string $nationalNumber a string buffer to store the national significant number in, in the case
1835
     *     that a country calling code was extracted. The number is appended to any existing contents.
1836
     *     If no country calling code was extracted, this will be left unchanged.
1837
     * @param bool $keepRawInput true if the country_code_source and preferred_carrier_code fields of
1838
     *     phoneNumber should be populated.
1839
     * @param PhoneNumber $phoneNumber the PhoneNumber object where the country_code and country_code_source need
1840
     *     to be populated. Note the country_code is always populated, whereas country_code_source is
1841
     *     only populated when keepCountryCodeSource is true.
1842
     * @return int the country calling code extracted or 0 if none could be extracted
1843
     * @throws NumberParseException
1844
     */
1845
    public function maybeExtractCountryCode(
1846
        $number,
1847
        PhoneMetadata $defaultRegionMetadata = null,
1848
        &$nationalNumber,
1849
        $keepRawInput,
1850
        PhoneNumber $phoneNumber
1851
    ) {
1852
        if (mb_strlen($number) == 0) {
1853
            return 0;
1854
        }
1855
        $fullNumber = $number;
1856
        // Set the default prefix to be something that will never match.
1857
        $possibleCountryIddPrefix = "NonMatch";
1858
        if ($defaultRegionMetadata !== null) {
1859
            $possibleCountryIddPrefix = $defaultRegionMetadata->getInternationalPrefix();
1860
        }
1861
        $countryCodeSource = $this->maybeStripInternationalPrefixAndNormalize($fullNumber, $possibleCountryIddPrefix);
1862
1863
        if ($keepRawInput) {
1864
            $phoneNumber->setCountryCodeSource($countryCodeSource);
1865
        }
1866
        if ($countryCodeSource != CountryCodeSource::FROM_DEFAULT_COUNTRY) {
1867
            if (mb_strlen($fullNumber) <= static::MIN_LENGTH_FOR_NSN) {
1868
                throw new NumberParseException(
1869
                    NumberParseException::TOO_SHORT_AFTER_IDD,
1870
                    "Phone number had an IDD, but after this was not long enough to be a viable phone number."
1871
                );
1872
            }
1873
            $potentialCountryCode = $this->extractCountryCode($fullNumber, $nationalNumber);
1874
1875
            if ($potentialCountryCode != 0) {
1876
                $phoneNumber->setCountryCode($potentialCountryCode);
1877
                return $potentialCountryCode;
1878
            }
1879
1880
            // If this fails, they must be using a strange country calling code that we don't recognize,
1881
            // or that doesn't exist.
1882
            throw new NumberParseException(
1883
                NumberParseException::INVALID_COUNTRY_CODE,
1884
                "Country calling code supplied was not recognised."
1885
            );
1886
        } elseif ($defaultRegionMetadata !== null) {
1887
            // Check to see if the number starts with the country calling code for the default region. If
1888
            // so, we remove the country calling code, and do some checks on the validity of the number
1889
            // before and after.
1890
            $defaultCountryCode = $defaultRegionMetadata->getCountryCode();
1891
            $defaultCountryCodeString = (string)$defaultCountryCode;
1892
            $normalizedNumber = (string)$fullNumber;
1893
            if (strpos($normalizedNumber, $defaultCountryCodeString) === 0) {
1894
                $potentialNationalNumber = substr($normalizedNumber, mb_strlen($defaultCountryCodeString));
1895
                $generalDesc = $defaultRegionMetadata->getGeneralDesc();
1896
                $validNumberPattern = $generalDesc->getNationalNumberPattern();
1897
                // Don't need the carrier code.
1898
                $carriercode = null;
1899
                $this->maybeStripNationalPrefixAndCarrierCode(
1900
                    $potentialNationalNumber,
1901
                    $defaultRegionMetadata,
1902
                    $carriercode
1903
                );
1904
                // If the number was not valid before but is valid now, or if it was too long before, we
1905
                // consider the number with the country calling code stripped to be a better result and
1906
                // keep that instead.
1907
                $validNumberPatternFullNumberMatcher = new Matcher($validNumberPattern, $fullNumber);
1908
                $validNumberPatternPotentialNationalNumberMatcher = new Matcher($validNumberPattern, $potentialNationalNumber);
1909
                if ((!$validNumberPatternFullNumberMatcher->matches()
1910
                        && $validNumberPatternPotentialNationalNumberMatcher->matches())
1911
                    || $this->testNumberLength($fullNumber, $defaultRegionMetadata) === ValidationResult::TOO_LONG
1912
                ) {
1913
                    $nationalNumber .= $potentialNationalNumber;
1914
                    if ($keepRawInput) {
1915
                        $phoneNumber->setCountryCodeSource(CountryCodeSource::FROM_NUMBER_WITHOUT_PLUS_SIGN);
1916
                    }
1917
                    $phoneNumber->setCountryCode($defaultCountryCode);
1918
                    return $defaultCountryCode;
1919
                }
1920
            }
1921
        }
1922
        // No country calling code present.
1923
        $phoneNumber->setCountryCode(0);
1924
        return 0;
1925
    }
1926
1927
    /**
1928
     * Strips any international prefix (such as +, 00, 011) present in the number provided, normalizes
1929
     * the resulting number, and indicates if an international prefix was present.
1930
     *
1931
     * @param string $number the non-normalized telephone number that we wish to strip any international
1932
     *     dialing prefix from.
1933
     * @param string $possibleIddPrefix string the international direct dialing prefix from the region we
1934
     *     think this number may be dialed in
1935
     * @return int the corresponding CountryCodeSource if an international dialing prefix could be
1936
     *     removed from the number, otherwise CountryCodeSource.FROM_DEFAULT_COUNTRY if the number did
1937
     *     not seem to be in international format.
1938
     */
1939
    public function maybeStripInternationalPrefixAndNormalize(&$number, $possibleIddPrefix)
1940
    {
1941
        if (mb_strlen($number) == 0) {
1942
            return CountryCodeSource::FROM_DEFAULT_COUNTRY;
1943
        }
1944
        $matches = array();
1945
        // Check to see if the number begins with one or more plus signs.
1946
        $match = preg_match('/^' . static::$PLUS_CHARS_PATTERN . '/' . static::REGEX_FLAGS, $number, $matches, PREG_OFFSET_CAPTURE);
1947
        if ($match > 0) {
1948
            $number = mb_substr($number, $matches[0][1] + mb_strlen($matches[0][0]));
1949
            // Can now normalize the rest of the number since we've consumed the "+" sign at the start.
1950
            $number = static::normalize($number);
1951
            return CountryCodeSource::FROM_NUMBER_WITH_PLUS_SIGN;
1952
        }
1953
        // Attempt to parse the first digits as an international prefix.
1954
        $iddPattern = $possibleIddPrefix;
1955
        $number = static::normalize($number);
1956
        return $this->parsePrefixAsIdd($iddPattern, $number)
1957
            ? CountryCodeSource::FROM_NUMBER_WITH_IDD
1958
            : CountryCodeSource::FROM_DEFAULT_COUNTRY;
1959
    }
1960
1961
    /**
1962
     * Normalizes a string of characters representing a phone number. This performs
1963
     * the following conversions:
1964
     *   Punctuation is stripped.
1965
     *   For ALPHA/VANITY numbers:
1966
     *   Letters are converted to their numeric representation on a telephone
1967
     *       keypad. The keypad used here is the one defined in ITU Recommendation
1968
     *       E.161. This is only done if there are 3 or more letters in the number,
1969
     *       to lessen the risk that such letters are typos.
1970
     *   For other numbers:
1971
     *   Wide-ascii digits are converted to normal ASCII (European) digits.
1972
     *   Arabic-Indic numerals are converted to European numerals.
1973
     *   Spurious alpha characters are stripped.
1974
     *
1975
     * @param string $number a string of characters representing a phone number.
1976
     * @return string the normalized string version of the phone number.
1977
     */
1978
    public static function normalize(&$number)
1979
    {
1980
        if (static::$ALPHA_PHONE_MAPPINGS === null) {
1981
            static::initAlphaPhoneMappings();
1982
        }
1983
1984
        $m = new Matcher(static::VALID_ALPHA_PHONE_PATTERN, $number);
1985
        if ($m->matches()) {
1986
            return static::normalizeHelper($number, static::$ALPHA_PHONE_MAPPINGS, true);
1987
        } else {
1988
            return static::normalizeDigitsOnly($number);
1989
        }
1990
    }
1991
1992
    /**
1993
     * Normalizes a string of characters representing a phone number. This converts wide-ascii and
1994
     * arabic-indic numerals to European numerals, and strips punctuation and alpha characters.
1995
     *
1996
     * @param $number string  a string of characters representing a phone number
1997
     * @return string the normalized string version of the phone number
1998
     */
1999
    public static function normalizeDigitsOnly($number)
2000
    {
2001
        return static::normalizeDigits($number, false /* strip non-digits */);
2002
    }
2003
2004
    /**
2005
     * @param string $number
2006
     * @param bool $keepNonDigits
2007
     * @return string
2008
     */
2009
    public static function normalizeDigits($number, $keepNonDigits)
2010
    {
2011
        $normalizedDigits = "";
2012
        $numberAsArray = preg_split('/(?<!^)(?!$)/u', $number);
2013
        foreach ($numberAsArray as $character) {
2014
            // Check if we are in the unicode number range
2015
            if (array_key_exists($character, static::$numericCharacters)) {
2016
                $normalizedDigits .= static::$numericCharacters[$character];
2017
            } elseif (is_numeric($character)) {
2018
                $normalizedDigits .= $character;
2019
            } elseif ($keepNonDigits) {
2020
                $normalizedDigits .= $character;
2021
            }
2022
        }
2023
        return $normalizedDigits;
2024
    }
2025
2026
    /**
2027
     * Strips the IDD from the start of the number if present. Helper function used by
2028
     * maybeStripInternationalPrefixAndNormalize.
2029
     * @param string $iddPattern
2030
     * @param string $number
2031
     * @return bool
2032
     */
2033
    protected function parsePrefixAsIdd($iddPattern, &$number)
2034
    {
2035
        $m = new Matcher($iddPattern, $number);
2036
        if ($m->lookingAt()) {
2037
            $matchEnd = $m->end();
2038
            // Only strip this if the first digit after the match is not a 0, since country calling codes
2039
            // cannot begin with 0.
2040
            $digitMatcher = new Matcher(static::$CAPTURING_DIGIT_PATTERN, substr($number, $matchEnd));
2041
            if ($digitMatcher->find()) {
2042
                $normalizedGroup = static::normalizeDigitsOnly($digitMatcher->group(1));
2043
                if ($normalizedGroup == "0") {
2044
                    return false;
2045
                }
2046
            }
2047
            $number = substr($number, $matchEnd);
2048
            return true;
2049
        }
2050
        return false;
2051
    }
2052
2053
    /**
2054
     * Extracts country calling code from fullNumber, returns it and places the remaining number in  nationalNumber.
2055
     * It assumes that the leading plus sign or IDD has already been removed.
2056
     * Returns 0 if fullNumber doesn't start with a valid country calling code, and leaves nationalNumber unmodified.
2057
     * @param string $fullNumber
2058
     * @param string $nationalNumber
2059
     * @return int
2060
     * @internal
2061
     */
2062
    public function extractCountryCode($fullNumber, &$nationalNumber)
2063
    {
2064
        if ((mb_strlen($fullNumber) == 0) || ($fullNumber[0] == '0')) {
2065
            // Country codes do not begin with a '0'.
2066
            return 0;
2067
        }
2068
        $numberLength = mb_strlen($fullNumber);
2069
        for ($i = 1; $i <= static::MAX_LENGTH_COUNTRY_CODE && $i <= $numberLength; $i++) {
2070
            $potentialCountryCode = (int)substr($fullNumber, 0, $i);
2071
            if (isset($this->countryCallingCodeToRegionCodeMap[$potentialCountryCode])) {
2072
                $nationalNumber .= substr($fullNumber, $i);
2073
                return $potentialCountryCode;
2074
            }
2075
        }
2076
        return 0;
2077
    }
2078
2079
    /**
2080
     * Strips any national prefix (such as 0, 1) present in the number provided.
2081
     *
2082
     * @param string $number the normalized telephone number that we wish to strip any national
2083
     *     dialing prefix from
2084
     * @param PhoneMetadata $metadata the metadata for the region that we think this number is from
2085
     * @param string $carrierCode a place to insert the carrier code if one is extracted
2086
     * @return bool true if a national prefix or carrier code (or both) could be extracted.
2087
     */
2088
    public function maybeStripNationalPrefixAndCarrierCode(&$number, PhoneMetadata $metadata, &$carrierCode)
2089
    {
2090
        $numberLength = mb_strlen($number);
2091
        $possibleNationalPrefix = $metadata->getNationalPrefixForParsing();
2092
        if ($numberLength == 0 || $possibleNationalPrefix === null || mb_strlen($possibleNationalPrefix) == 0) {
2093
            // Early return for numbers of zero length.
2094
            return false;
2095
        }
2096
2097
        // Attempt to parse the first digits as a national prefix.
2098
        $prefixMatcher = new Matcher($possibleNationalPrefix, $number);
2099
        if ($prefixMatcher->lookingAt()) {
2100
            $nationalNumberRule = $metadata->getGeneralDesc()->getNationalNumberPattern();
2101
            // Check if the original number is viable.
2102
            $nationalNumberRuleMatcher = new Matcher($nationalNumberRule, $number);
2103
            $isViableOriginalNumber = $nationalNumberRuleMatcher->matches();
2104
            // $prefixMatcher->group($numOfGroups) === null implies nothing was captured by the capturing
2105
            // groups in $possibleNationalPrefix; therefore, no transformation is necessary, and we just
2106
            // remove the national prefix
2107
            $numOfGroups = $prefixMatcher->groupCount();
2108
            $transformRule = $metadata->getNationalPrefixTransformRule();
2109
            if ($transformRule === null
2110
                || mb_strlen($transformRule) == 0
2111
                || $prefixMatcher->group($numOfGroups - 1) === null
2112
            ) {
2113
                // If the original number was viable, and the resultant number is not, we return.
2114
                $matcher = new Matcher($nationalNumberRule, substr($number, $prefixMatcher->end()));
2115
                if ($isViableOriginalNumber && !$matcher->matches()) {
2116
                    return false;
2117
                }
2118
                if ($carrierCode !== null && $numOfGroups > 0 && $prefixMatcher->group($numOfGroups) !== null) {
2119
                    $carrierCode .= $prefixMatcher->group(1);
2120
                }
2121
2122
                $number = substr($number, $prefixMatcher->end());
2123
                return true;
2124
            } else {
2125
                // Check that the resultant number is still viable. If not, return. Check this by copying
2126
                // the string and making the transformation on the copy first.
2127
                $transformedNumber = $number;
2128
                $transformedNumber = substr_replace(
2129
                    $transformedNumber,
2130
                    $prefixMatcher->replaceFirst($transformRule),
2131
                    0,
2132
                    $numberLength
2133
                );
2134
                $matcher = new Matcher($nationalNumberRule, $transformedNumber);
2135
                if ($isViableOriginalNumber && !$matcher->matches()) {
2136
                    return false;
2137
                }
2138
                if ($carrierCode !== null && $numOfGroups > 1) {
2139
                    $carrierCode .= $prefixMatcher->group(1);
2140
                }
2141
                $number = substr_replace($number, $transformedNumber, 0, mb_strlen($number));
2142
                return true;
2143
            }
2144
        }
2145
        return false;
2146
    }
2147
2148
    /**
2149
     * Convenience wrapper around isPossibleNumberForTypeWithReason. Instead of returning the reason
2150
     * for failure, this method returns a boolean value
2151
     *
2152
     * @param PhoneNumber $number The number that needs to be checked
2153
     * @param int $type PhoneNumberType The type we are interested in
2154
     * @return bool true if the number is possible for this particular type
2155
     */
2156
    public function isPossibleNumberForType(PhoneNumber $number, $type)
2157
    {
2158
        return $this->isPossibleNumberForTypeWithReason($number, $type) === ValidationResult::IS_POSSIBLE;
2159
    }
2160
2161
    /**
2162
     * Helper method to check a number against possible lengths for this number type, and determine
2163
     * whether it matches, or is too short or too long. Currently, if a number pattern suggests that
2164
     * numbers of length 7 and 10 are possible, and a number in between these possible lengths is
2165
     * entered, such as of length 8, this will return TOO_LONG.
2166
     *
2167
     * @param string $number
2168
     * @param PhoneMetadata $metadata
2169
     * @param int $type PhoneNumberType
2170
     * @return int ValidationResult
2171
     */
2172
    protected function testNumberLength($number, PhoneMetadata $metadata, $type = PhoneNumberType::UNKNOWN)
2173
    {
2174
        $descForType = $this->getNumberDescByType($metadata, $type);
2175
        // There should always be "possibleLengths" set for every element. This is declared in the XML
2176
        // schema which is verified by PhoneNumberMetadataSchemaTest.
2177
        // For size efficiency, where a sub-description (e.g. fixed-line) has the same possibleLengths
2178
        // as the parent, this is missing, so we fall back to the general desc (where no numbers of the
2179
        // type exist at all, there is one possible length (-1) which is guaranteed not to match the
2180
        // length of any real phone number).
2181
        $possibleLengths = (count($descForType->getPossibleLength()) === 0)
2182
            ? $metadata->getGeneralDesc()->getPossibleLength() : $descForType->getPossibleLength();
2183
2184
        $localLengths = $descForType->getPossibleLengthLocalOnly();
2185
2186
        if ($type === PhoneNumberType::FIXED_LINE_OR_MOBILE) {
2187
            if (!static::descHasPossibleNumberData($this->getNumberDescByType($metadata, PhoneNumberType::FIXED_LINE))) {
2188
                // The rate case has been encountered where no fixedLine data is available (true for some
2189
                // non-geographical entities), so we just check mobile.
2190
                return $this->testNumberLength($number, $metadata, PhoneNumberType::MOBILE);
2191
            } else {
2192
                $mobileDesc = $this->getNumberDescByType($metadata, PhoneNumberType::MOBILE);
2193
                if (static::descHasPossibleNumberData($mobileDesc)) {
2194
                    // Note that when adding the possible lengths from mobile, we have to again check they
2195
                    // aren't empty since if they are this indicates they are the same as the general desc and
2196
                    // should be obtained from there.
2197
                    $possibleLengths = array_merge($possibleLengths,
2198
                        (count($mobileDesc->getPossibleLength()) === 0)
2199
                            ? $metadata->getGeneralDesc()->getPossibleLength() : $mobileDesc->getPossibleLength());
2200
2201
                    // The current list is sorted; we need to merge in the new list and re-sort (duplicates
2202
                    // are okay). Sorting isn't so expensive because the lists are very small.
2203
                    sort($possibleLengths);
2204
2205
                    if (count($localLengths) === 0) {
2206
                        $localLengths = $mobileDesc->getPossibleLengthLocalOnly();
2207
                    } else {
2208
                        $localLengths = array_merge($localLengths, $mobileDesc->getPossibleLengthLocalOnly());
2209
                        sort($localLengths);
2210
                    }
2211
                }
2212
            }
2213
        }
2214
2215
2216
        // If the type is not supported at all (indicated by the possible lengths containing -1 at this
2217
        // point) we return invalid length.
2218
2219
        if ($possibleLengths[0] === -1) {
2220
            return ValidationResult::INVALID_LENGTH;
2221
        }
2222
2223
        $actualLength = mb_strlen($number);
2224
2225
        if (in_array($actualLength, $localLengths)) {
2226
            return ValidationResult::IS_POSSIBLE;
2227
        }
2228
2229
        $minimumLength = reset($possibleLengths);
2230
        if ($minimumLength == $actualLength) {
2231
            return ValidationResult::IS_POSSIBLE;
2232
        } elseif ($minimumLength > $actualLength) {
2233
            return ValidationResult::TOO_SHORT;
2234
        } elseif (isset($possibleLengths[count($possibleLengths) - 1]) && $possibleLengths[count($possibleLengths) - 1] < $actualLength) {
2235
            return ValidationResult::TOO_LONG;
2236
        }
2237
2238
        // Note that actually the number is not too long if possibleLengths does not contain the length:
2239
        // we know it is less than the highest possible number length, and higher than the lowest
2240
        // possible number length. However, we don't currently have an enum to express this, so we
2241
        // return TOO_LONG in the short-term.
2242
        // We skip the first element; we've already checked it.
2243
        array_shift($possibleLengths);
2244
        return in_array($actualLength, $possibleLengths) ? ValidationResult::IS_POSSIBLE : ValidationResult::TOO_LONG;
2245
    }
2246
2247
    /**
2248
     * Returns a list with the region codes that match the specific country calling code. For
2249
     * non-geographical country calling codes, the region code 001 is returned. Also, in the case
2250
     * of no region code being found, an empty list is returned.
2251
     * @param int $countryCallingCode
2252
     * @return array
2253
     */
2254
    public function getRegionCodesForCountryCode($countryCallingCode)
2255
    {
2256
        $regionCodes = isset($this->countryCallingCodeToRegionCodeMap[$countryCallingCode]) ? $this->countryCallingCodeToRegionCodeMap[$countryCallingCode] : null;
2257
        return $regionCodes === null ? array() : $regionCodes;
2258
    }
2259
2260
    /**
2261
     * Returns the country calling code for a specific region. For example, this would be 1 for the
2262
     * United States, and 64 for New Zealand. Assumes the region is already valid.
2263
     *
2264
     * @param string $regionCode the region that we want to get the country calling code for
2265
     * @return int the country calling code for the region denoted by regionCode
2266
     */
2267
    public function getCountryCodeForRegion($regionCode)
2268
    {
2269
        if (!$this->isValidRegionCode($regionCode)) {
2270
            return 0;
2271
        }
2272
        return $this->getCountryCodeForValidRegion($regionCode);
2273
    }
2274
2275
    /**
2276
     * Returns the country calling code for a specific region. For example, this would be 1 for the
2277
     * United States, and 64 for New Zealand. Assumes the region is already valid.
2278
     *
2279
     * @param string $regionCode the region that we want to get the country calling code for
2280
     * @return int the country calling code for the region denoted by regionCode
2281
     * @throws \InvalidArgumentException if the region is invalid
2282
     */
2283
    protected function getCountryCodeForValidRegion($regionCode)
2284
    {
2285
        $metadata = $this->getMetadataForRegion($regionCode);
2286
        if ($metadata === null) {
2287
            throw new \InvalidArgumentException("Invalid region code: " . $regionCode);
2288
        }
2289
        return $metadata->getCountryCode();
2290
    }
2291
2292
    /**
2293
     * Returns a number formatted in such a way that it can be dialed from a mobile phone in a
2294
     * specific region. If the number cannot be reached from the region (e.g. some countries block
2295
     * toll-free numbers from being called outside of the country), the method returns an empty
2296
     * string.
2297
     *
2298
     * @param PhoneNumber $number the phone number to be formatted
2299
     * @param string $regionCallingFrom the region where the call is being placed
2300
     * @param boolean $withFormatting whether the number should be returned with formatting symbols, such as
2301
     *     spaces and dashes.
2302
     * @return string the formatted phone number
2303
     */
2304
    public function formatNumberForMobileDialing(PhoneNumber $number, $regionCallingFrom, $withFormatting)
2305
    {
2306
        $countryCallingCode = $number->getCountryCode();
2307
        if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
2308
            return $number->hasRawInput() ? $number->getRawInput() : "";
2309
        }
2310
2311
        $formattedNumber = "";
2312
        // Clear the extension, as that part cannot normally be dialed together with the main number.
2313
        $numberNoExt = new PhoneNumber();
2314
        $numberNoExt->mergeFrom($number)->clearExtension();
2315
        $regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
2316
        $numberType = $this->getNumberType($numberNoExt);
2317
        $isValidNumber = ($numberType !== PhoneNumberType::UNKNOWN);
2318
        if ($regionCallingFrom == $regionCode) {
2319
            $isFixedLineOrMobile = ($numberType == PhoneNumberType::FIXED_LINE) || ($numberType == PhoneNumberType::MOBILE) || ($numberType == PhoneNumberType::FIXED_LINE_OR_MOBILE);
2320
            // Carrier codes may be needed in some countries. We handle this here.
2321
            if ($regionCode == "CO" && $numberType == PhoneNumberType::FIXED_LINE) {
2322
                $formattedNumber = $this->formatNationalNumberWithCarrierCode(
2323
                    $numberNoExt,
2324
                    static::COLOMBIA_MOBILE_TO_FIXED_LINE_PREFIX
2325
                );
2326
            } elseif ($regionCode == "BR" && $isFixedLineOrMobile) {
2327
                // Historically, we set this to an empty string when parsing with raw input if none was
2328
                // found in the input string. However, this doesn't result in a number we can dial. For this
2329
                // reason, we treat the empty string the same as if it isn't set at all.
2330
                $formattedNumber = mb_strlen($numberNoExt->getPreferredDomesticCarrierCode()) > 0
2331
                    ? $this->formatNationalNumberWithPreferredCarrierCode($numberNoExt, "")
2332
                    // Brazilian fixed line and mobile numbers need to be dialed with a carrier code when
2333
                    // called within Brazil. Without that, most of the carriers won't connect the call.
2334
                    // Because of that, we return an empty string here.
2335
                    : "";
2336
            } elseif ($isValidNumber && $regionCode == "HU") {
2337
                // The national format for HU numbers doesn't contain the national prefix, because that is
2338
                // how numbers are normally written down. However, the national prefix is obligatory when
2339
                // dialing from a mobile phone, except for short numbers. As a result, we add it back here
2340
                // if it is a valid regular length phone number.
2341
                $formattedNumber = $this->getNddPrefixForRegion(
2342
                        $regionCode,
2343
                        true /* strip non-digits */
2344
                    ) . " " . $this->format($numberNoExt, PhoneNumberFormat::NATIONAL);
2345
            } elseif ($countryCallingCode === static::NANPA_COUNTRY_CODE) {
2346
                // For NANPA countries, we output international format for numbers that can be dialed
2347
                // internationally, since that always works, except for numbers which might potentially be
2348
                // short numbers, which are always dialled in national format.
2349
                $regionMetadata = $this->getMetadataForRegion($regionCallingFrom);
2350
                if ($this->canBeInternationallyDialled($numberNoExt)
2351
                    && $this->testNumberLength($this->getNationalSignificantNumber($numberNoExt), $regionMetadata)
0 ignored issues
show
Bug introduced by
It seems like $regionMetadata defined by $this->getMetadataForRegion($regionCallingFrom) on line 2349 can be null; however, libphonenumber\PhoneNumberUtil::testNumberLength() does not accept null, maybe add an additional type check?

Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code:

/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
2352
                    !== ValidationResult::TOO_SHORT
2353
                ) {
2354
                    $formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::INTERNATIONAL);
2355
                } else {
2356
                    $formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::NATIONAL);
2357
                }
2358
            } else {
2359
                // For non-geographical countries, Mexican and Chilean fixed line and mobile numbers, we
2360
                // output international format for numbers that can be dialed internationally as that always
2361
                // works.
2362
                if (($regionCode == static::REGION_CODE_FOR_NON_GEO_ENTITY ||
2363
                        // MX fixed line and mobile numbers should always be formatted in international format,
2364
                        // even when dialed within MX. For national format to work, a carrier code needs to be
2365
                        // used, and the correct carrier code depends on if the caller and callee are from the
2366
                        // same local area. It is trickier to get that to work correctly than using
2367
                        // international format, which is tested to work fine on all carriers.
2368
                        // CL fixed line numbers need the national prefix when dialing in the national format,
2369
                        // but don't have it when used for display. The reverse is true for mobile numbers.
2370
                        // As a result, we output them in the international format to make it work.
2371
                        (($regionCode == "MX" || $regionCode == "CL") && $isFixedLineOrMobile)) && $this->canBeInternationallyDialled(
2372
                        $numberNoExt
2373
                    )
2374
                ) {
2375
                    $formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::INTERNATIONAL);
2376
                } else {
2377
                    $formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::NATIONAL);
2378
                }
2379
            }
2380
        } elseif ($isValidNumber && $this->canBeInternationallyDialled($numberNoExt)) {
2381
            // We assume that short numbers are not diallable from outside their region, so if a number
2382
            // is not a valid regular length phone number, we treat it as if it cannot be internationally
2383
            // dialled.
2384
            return $withFormatting ?
2385
                $this->format($numberNoExt, PhoneNumberFormat::INTERNATIONAL) :
2386
                $this->format($numberNoExt, PhoneNumberFormat::E164);
2387
        }
2388
        return $withFormatting ? $formattedNumber : static::normalizeDiallableCharsOnly($formattedNumber);
2389
    }
2390
2391
    /**
2392
     * Formats a phone number in national format for dialing using the carrier as specified in the
2393
     * {@code carrierCode}. The {@code carrierCode} will always be used regardless of whether the
2394
     * phone number already has a preferred domestic carrier code stored. If {@code carrierCode}
2395
     * contains an empty string, returns the number in national format without any carrier code.
2396
     *
2397
     * @param PhoneNumber $number the phone number to be formatted
2398
     * @param string $carrierCode the carrier selection code to be used
2399
     * @return string the formatted phone number in national format for dialing using the carrier as
2400
     * specified in the {@code carrierCode}
2401
     */
2402
    public function formatNationalNumberWithCarrierCode(PhoneNumber $number, $carrierCode)
2403
    {
2404
        $countryCallingCode = $number->getCountryCode();
2405
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
2406
        if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
2407
            return $nationalSignificantNumber;
2408
        }
2409
2410
        // Note getRegionCodeForCountryCode() is used because formatting information for regions which
2411
        // share a country calling code is contained by only one region for performance reasons. For
2412
        // example, for NANPA regions it will be contained in the metadata for US.
2413
        $regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
2414
        // Metadata cannot be null because the country calling code is valid.
2415
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode);
2416
2417
        $formattedNumber = $this->formatNsn(
2418
            $nationalSignificantNumber,
2419
            $metadata,
0 ignored issues
show
Bug introduced by
It seems like $metadata defined by $this->getMetadataForReg...llingCode, $regionCode) on line 2415 can be null; however, libphonenumber\PhoneNumberUtil::formatNsn() does not accept null, maybe add an additional type check?

Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code:

/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
2420
            PhoneNumberFormat::NATIONAL,
2421
            $carrierCode
2422
        );
2423
        $this->maybeAppendFormattedExtension($number, $metadata, PhoneNumberFormat::NATIONAL, $formattedNumber);
2424
        $this->prefixNumberWithCountryCallingCode(
2425
            $countryCallingCode,
2426
            PhoneNumberFormat::NATIONAL,
2427
            $formattedNumber
2428
        );
2429
        return $formattedNumber;
2430
    }
2431
2432
    /**
2433
     * Formats a phone number in national format for dialing using the carrier as specified in the
2434
     * preferredDomesticCarrierCode field of the PhoneNumber object passed in. If that is missing,
2435
     * use the {@code fallbackCarrierCode} passed in instead. If there is no
2436
     * {@code preferredDomesticCarrierCode}, and the {@code fallbackCarrierCode} contains an empty
2437
     * string, return the number in national format without any carrier code.
2438
     *
2439
     * <p>Use {@link #formatNationalNumberWithCarrierCode} instead if the carrier code passed in
2440
     * should take precedence over the number's {@code preferredDomesticCarrierCode} when formatting.
2441
     *
2442
     * @param PhoneNumber $number the phone number to be formatted
2443
     * @param string $fallbackCarrierCode the carrier selection code to be used, if none is found in the
2444
     *     phone number itself
2445
     * @return string the formatted phone number in national format for dialing using the number's
2446
     *     {@code preferredDomesticCarrierCode}, or the {@code fallbackCarrierCode} passed in if
2447
     *     none is found
2448
     */
2449
    public function formatNationalNumberWithPreferredCarrierCode(PhoneNumber $number, $fallbackCarrierCode)
2450
    {
2451
        return $this->formatNationalNumberWithCarrierCode(
2452
            $number,
2453
            // Historically, we set this to an empty string when parsing with raw input if none was
2454
            // found in the input string. However, this doesn't result in a number we can dial. For this
2455
            // reason, we treat the empty string the same as if it isn't set at all.
2456
            mb_strlen($number->getPreferredDomesticCarrierCode()) > 0
2457
                ? $number->getPreferredDomesticCarrierCode()
2458
                : $fallbackCarrierCode
2459
        );
2460
    }
2461
2462
    /**
2463
     * Returns true if the number can be dialled from outside the region, or unknown. If the number
2464
     * can only be dialled from within the region, returns false. Does not check the number is a valid
2465
     * number.
2466
     * TODO: Make this method public when we have enough metadata to make it worthwhile.
2467
     *
2468
     * @param PhoneNumber $number the phone-number for which we want to know whether it is diallable from outside the region
2469
     * @return bool
2470
     */
2471
    public function canBeInternationallyDialled(PhoneNumber $number)
2472
    {
2473
        $metadata = $this->getMetadataForRegion($this->getRegionCodeForNumber($number));
2474
        if ($metadata === null) {
2475
            // Note numbers belonging to non-geographical entities (e.g. +800 numbers) are always
2476
            // internationally diallable, and will be caught here.
2477
            return true;
2478
        }
2479
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
2480
        return !$this->isNumberMatchingDesc($nationalSignificantNumber, $metadata->getNoInternationalDialling());
2481
    }
2482
2483
    /**
2484
     * Normalizes a string of characters representing a phone number. This strips all characters which
2485
     * are not diallable on a mobile phone keypad (including all non-ASCII digits).
2486
     *
2487
     * @param string $number a string of characters representing a phone number
2488
     * @return string the normalized string version of the phone number
2489
     */
2490
    public static function normalizeDiallableCharsOnly($number)
2491
    {
2492
        if (count(static::$DIALLABLE_CHAR_MAPPINGS) === 0) {
2493
            static::initDiallableCharMappings();
2494
        }
2495
2496
        return static::normalizeHelper($number, static::$DIALLABLE_CHAR_MAPPINGS, true /* remove non matches */);
2497
    }
2498
2499
    /**
2500
     * Formats a phone number for out-of-country dialing purposes.
2501
     *
2502
     * Note that in this version, if the number was entered originally using alpha characters and
2503
     * this version of the number is stored in raw_input, this representation of the number will be
2504
     * used rather than the digit representation. Grouping information, as specified by characters
2505
     * such as "-" and " ", will be retained.
2506
     *
2507
     * <p><b>Caveats:</b></p>
2508
     * <ul>
2509
     *  <li> This will not produce good results if the country calling code is both present in the raw
2510
     *       input _and_ is the start of the national number. This is not a problem in the regions
2511
     *       which typically use alpha numbers.
2512
     *  <li> This will also not produce good results if the raw input has any grouping information
2513
     *       within the first three digits of the national number, and if the function needs to strip
2514
     *       preceding digits/words in the raw input before these digits. Normally people group the
2515
     *       first three digits together so this is not a huge problem - and will be fixed if it
2516
     *       proves to be so.
2517
     * </ul>
2518
     *
2519
     * @param PhoneNumber $number the phone number that needs to be formatted
2520
     * @param String $regionCallingFrom the region where the call is being placed
2521
     * @return String the formatted phone number
2522
     */
2523
    public function formatOutOfCountryKeepingAlphaChars(PhoneNumber $number, $regionCallingFrom)
2524
    {
2525
        $rawInput = $number->getRawInput();
2526
        // If there is no raw input, then we can't keep alpha characters because there aren't any.
2527
        // In this case, we return formatOutOfCountryCallingNumber.
2528
        if (mb_strlen($rawInput) == 0) {
2529
            return $this->formatOutOfCountryCallingNumber($number, $regionCallingFrom);
2530
        }
2531
        $countryCode = $number->getCountryCode();
2532
        if (!$this->hasValidCountryCallingCode($countryCode)) {
2533
            return $rawInput;
2534
        }
2535
        // Strip any prefix such as country calling code, IDD, that was present. We do this by comparing
2536
        // the number in raw_input with the parsed number.
2537
        // To do this, first we normalize punctuation. We retain number grouping symbols such as " "
2538
        // only.
2539
        $rawInput = $this->normalizeHelper($rawInput, static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS, true);
2540
        // Now we trim everything before the first three digits in the parsed number. We choose three
2541
        // because all valid alpha numbers have 3 digits at the start - if it does not, then we don't
2542
        // trim anything at all. Similarly, if the national number was less than three digits, we don't
2543
        // trim anything at all.
2544
        $nationalNumber = $this->getNationalSignificantNumber($number);
2545
        if (mb_strlen($nationalNumber) > 3) {
2546
            $firstNationalNumberDigit = strpos($rawInput, substr($nationalNumber, 0, 3));
2547
            if ($firstNationalNumberDigit !== false) {
2548
                $rawInput = substr($rawInput, $firstNationalNumberDigit);
2549
            }
2550
        }
2551
        $metadataForRegionCallingFrom = $this->getMetadataForRegion($regionCallingFrom);
2552
        if ($countryCode == static::NANPA_COUNTRY_CODE) {
2553
            if ($this->isNANPACountry($regionCallingFrom)) {
2554
                return $countryCode . " " . $rawInput;
2555
            }
2556
        } elseif ($metadataForRegionCallingFrom !== null &&
2557
            $countryCode == $this->getCountryCodeForValidRegion($regionCallingFrom)
2558
        ) {
2559
            $formattingPattern =
2560
                $this->chooseFormattingPatternForNumber(
2561
                    $metadataForRegionCallingFrom->numberFormats(),
2562
                    $nationalNumber
2563
                );
2564
            if ($formattingPattern === null) {
2565
                // If no pattern above is matched, we format the original input.
2566
                return $rawInput;
2567
            }
2568
            $newFormat = new NumberFormat();
2569
            $newFormat->mergeFrom($formattingPattern);
2570
            // The first group is the first group of digits that the user wrote together.
2571
            $newFormat->setPattern("(\\d+)(.*)");
2572
            // Here we just concatenate them back together after the national prefix has been fixed.
2573
            $newFormat->setFormat("$1$2");
2574
            // Now we format using this pattern instead of the default pattern, but with the national
2575
            // prefix prefixed if necessary.
2576
            // This will not work in the cases where the pattern (and not the leading digits) decide
2577
            // whether a national prefix needs to be used, since we have overridden the pattern to match
2578
            // anything, but that is not the case in the metadata to date.
2579
            return $this->formatNsnUsingPattern($rawInput, $newFormat, PhoneNumberFormat::NATIONAL);
2580
        }
2581
        $internationalPrefixForFormatting = "";
2582
        // If an unsupported region-calling-from is entered, or a country with multiple international
2583
        // prefixes, the international format of the number is returned, unless there is a preferred
2584
        // international prefix.
2585
        if ($metadataForRegionCallingFrom !== null) {
2586
            $internationalPrefix = $metadataForRegionCallingFrom->getInternationalPrefix();
2587
            $uniqueInternationalPrefixMatcher = new Matcher(static::UNIQUE_INTERNATIONAL_PREFIX, $internationalPrefix);
2588
            $internationalPrefixForFormatting =
2589
                $uniqueInternationalPrefixMatcher->matches()
2590
                    ? $internationalPrefix
2591
                    : $metadataForRegionCallingFrom->getPreferredInternationalPrefix();
2592
        }
2593
        $formattedNumber = $rawInput;
2594
        $regionCode = $this->getRegionCodeForCountryCode($countryCode);
2595
        // Metadata cannot be null because the country calling code is valid.
2596
        $metadataForRegion = $this->getMetadataForRegionOrCallingCode($countryCode, $regionCode);
2597
        $this->maybeAppendFormattedExtension(
2598
            $number,
2599
            $metadataForRegion,
2600
            PhoneNumberFormat::INTERNATIONAL,
2601
            $formattedNumber
2602
        );
2603
        if (mb_strlen($internationalPrefixForFormatting) > 0) {
2604
            $formattedNumber = $internationalPrefixForFormatting . " " . $countryCode . " " . $formattedNumber;
2605
        } else {
2606
            // Invalid region entered as country-calling-from (so no metadata was found for it) or the
2607
            // region chosen has multiple international dialling prefixes.
2608
            $this->prefixNumberWithCountryCallingCode(
2609
                $countryCode,
2610
                PhoneNumberFormat::INTERNATIONAL,
2611
                $formattedNumber
2612
            );
2613
        }
2614
        return $formattedNumber;
2615
    }
2616
2617
    /**
2618
     * Formats a phone number for out-of-country dialing purposes. If no regionCallingFrom is
2619
     * supplied, we format the number in its INTERNATIONAL format. If the country calling code is the
2620
     * same as that of the region where the number is from, then NATIONAL formatting will be applied.
2621
     *
2622
     * <p>If the number itself has a country calling code of zero or an otherwise invalid country
2623
     * calling code, then we return the number with no formatting applied.
2624
     *
2625
     * <p>Note this function takes care of the case for calling inside of NANPA and between Russia and
2626
     * Kazakhstan (who share the same country calling code). In those cases, no international prefix
2627
     * is used. For regions which have multiple international prefixes, the number in its
2628
     * INTERNATIONAL format will be returned instead.
2629
     *
2630
     * @param PhoneNumber $number the phone number to be formatted
2631
     * @param string $regionCallingFrom the region where the call is being placed
2632
     * @return string  the formatted phone number
2633
     */
2634
    public function formatOutOfCountryCallingNumber(PhoneNumber $number, $regionCallingFrom)
2635
    {
2636
        if (!$this->isValidRegionCode($regionCallingFrom)) {
2637
            return $this->format($number, PhoneNumberFormat::INTERNATIONAL);
2638
        }
2639
        $countryCallingCode = $number->getCountryCode();
2640
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
2641
        if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
2642
            return $nationalSignificantNumber;
2643
        }
2644
        if ($countryCallingCode == static::NANPA_COUNTRY_CODE) {
2645
            if ($this->isNANPACountry($regionCallingFrom)) {
2646
                // For NANPA regions, return the national format for these regions but prefix it with the
2647
                // country calling code.
2648
                return $countryCallingCode . " " . $this->format($number, PhoneNumberFormat::NATIONAL);
2649
            }
2650
        } elseif ($countryCallingCode == $this->getCountryCodeForValidRegion($regionCallingFrom)) {
2651
            // If regions share a country calling code, the country calling code need not be dialled.
2652
            // This also applies when dialling within a region, so this if clause covers both these cases.
2653
            // Technically this is the case for dialling from La Reunion to other overseas departments of
2654
            // France (French Guiana, Martinique, Guadeloupe), but not vice versa - so we don't cover this
2655
            // edge case for now and for those cases return the version including country calling code.
2656
            // Details here: http://www.petitfute.com/voyage/225-info-pratiques-reunion
2657
            return $this->format($number, PhoneNumberFormat::NATIONAL);
2658
        }
2659
        // Metadata cannot be null because we checked 'isValidRegionCode()' above.
2660
        $metadataForRegionCallingFrom = $this->getMetadataForRegion($regionCallingFrom);
2661
2662
        $internationalPrefix = $metadataForRegionCallingFrom->getInternationalPrefix();
2663
2664
        // For regions that have multiple international prefixes, the international format of the
2665
        // number is returned, unless there is a preferred international prefix.
2666
        $internationalPrefixForFormatting = "";
2667
        $uniqueInternationalPrefixMatcher = new Matcher(static::UNIQUE_INTERNATIONAL_PREFIX, $internationalPrefix);
2668
2669
        if ($uniqueInternationalPrefixMatcher->matches()) {
2670
            $internationalPrefixForFormatting = $internationalPrefix;
2671
        } elseif ($metadataForRegionCallingFrom->hasPreferredInternationalPrefix()) {
2672
            $internationalPrefixForFormatting = $metadataForRegionCallingFrom->getPreferredInternationalPrefix();
2673
        }
2674
2675
        $regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
2676
        // Metadata cannot be null because the country calling code is valid.
2677
        $metadataForRegion = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode);
2678
        $formattedNationalNumber = $this->formatNsn(
2679
            $nationalSignificantNumber,
2680
            $metadataForRegion,
0 ignored issues
show
Bug introduced by
It seems like $metadataForRegion defined by $this->getMetadataForReg...llingCode, $regionCode) on line 2677 can be null; however, libphonenumber\PhoneNumberUtil::formatNsn() does not accept null, maybe add an additional type check?

Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code:

/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
2681
            PhoneNumberFormat::INTERNATIONAL
2682
        );
2683
        $formattedNumber = $formattedNationalNumber;
2684
        $this->maybeAppendFormattedExtension(
2685
            $number,
2686
            $metadataForRegion,
2687
            PhoneNumberFormat::INTERNATIONAL,
2688
            $formattedNumber
2689
        );
2690
        if (mb_strlen($internationalPrefixForFormatting) > 0) {
2691
            $formattedNumber = $internationalPrefixForFormatting . " " . $countryCallingCode . " " . $formattedNumber;
2692
        } else {
2693
            $this->prefixNumberWithCountryCallingCode(
2694
                $countryCallingCode,
2695
                PhoneNumberFormat::INTERNATIONAL,
2696
                $formattedNumber
2697
            );
2698
        }
2699
        return $formattedNumber;
2700
    }
2701
2702
    /**
2703
     * Checks if this is a region under the North American Numbering Plan Administration (NANPA).
2704
     * @param string $regionCode
2705
     * @return boolean true if regionCode is one of the regions under NANPA
2706
     */
2707
    public function isNANPACountry($regionCode)
2708
    {
2709
        return in_array($regionCode, $this->nanpaRegions);
2710
    }
2711
2712
    /**
2713
     * Formats a phone number using the original phone number format that the number is parsed from.
2714
     * The original format is embedded in the country_code_source field of the PhoneNumber object
2715
     * passed in. If such information is missing, the number will be formatted into the NATIONAL
2716
     * format by default. When the number contains a leading zero and this is unexpected for this
2717
     * country, or we don't have a formatting pattern for the number, the method returns the raw input
2718
     * when it is available.
2719
     *
2720
     * Note this method guarantees no digit will be inserted, removed or modified as a result of
2721
     * formatting.
2722
     *
2723
     * @param PhoneNumber $number the phone number that needs to be formatted in its original number format
2724
     * @param string $regionCallingFrom the region whose IDD needs to be prefixed if the original number
2725
     *     has one
2726
     * @return string the formatted phone number in its original number format
2727
     */
2728
    public function formatInOriginalFormat(PhoneNumber $number, $regionCallingFrom)
2729
    {
2730
        if ($number->hasRawInput() &&
2731
            ($this->hasUnexpectedItalianLeadingZero($number) || !$this->hasFormattingPatternForNumber($number))
2732
        ) {
2733
            // We check if we have the formatting pattern because without that, we might format the number
2734
            // as a group without national prefix.
2735
            return $number->getRawInput();
2736
        }
2737
        if (!$number->hasCountryCodeSource()) {
2738
            return $this->format($number, PhoneNumberFormat::NATIONAL);
2739
        }
2740
        switch ($number->getCountryCodeSource()) {
2741
            case CountryCodeSource::FROM_NUMBER_WITH_PLUS_SIGN:
2742
                $formattedNumber = $this->format($number, PhoneNumberFormat::INTERNATIONAL);
2743
                break;
2744
            case CountryCodeSource::FROM_NUMBER_WITH_IDD:
2745
                $formattedNumber = $this->formatOutOfCountryCallingNumber($number, $regionCallingFrom);
2746
                break;
2747
            case CountryCodeSource::FROM_NUMBER_WITHOUT_PLUS_SIGN:
2748
                $formattedNumber = substr($this->format($number, PhoneNumberFormat::INTERNATIONAL), 1);
2749
                break;
2750
            case CountryCodeSource::FROM_DEFAULT_COUNTRY:
2751
                // Fall-through to default case.
2752
            default:
0 ignored issues
show
Coding Style introduced by
The default body in a switch statement must start on the line following the statement.

According to the PSR-2, the body of a default statement must start on the line immediately following the statement.

switch ($expr) {
    default:
        doSomething(); //right
        break;
}


switch ($expr) {
    default:

        doSomething(); //wrong
        break;
}

To learn more about the PSR-2 coding standard, please refer to the PHP-Fig.

Loading history...
2753
2754
                $regionCode = $this->getRegionCodeForCountryCode($number->getCountryCode());
2755
                // We strip non-digits from the NDD here, and from the raw input later, so that we can
2756
                // compare them easily.
2757
                $nationalPrefix = $this->getNddPrefixForRegion($regionCode, true /* strip non-digits */);
2758
                $nationalFormat = $this->format($number, PhoneNumberFormat::NATIONAL);
2759
                if ($nationalPrefix === null || mb_strlen($nationalPrefix) == 0) {
2760
                    // If the region doesn't have a national prefix at all, we can safely return the national
2761
                    // format without worrying about a national prefix being added.
2762
                    $formattedNumber = $nationalFormat;
2763
                    break;
2764
                }
2765
                // Otherwise, we check if the original number was entered with a national prefix.
2766
                if ($this->rawInputContainsNationalPrefix(
2767
                    $number->getRawInput(),
2768
                    $nationalPrefix,
2769
                    $regionCode
2770
                )
2771
                ) {
2772
                    // If so, we can safely return the national format.
2773
                    $formattedNumber = $nationalFormat;
2774
                    break;
2775
                }
2776
                // Metadata cannot be null here because getNddPrefixForRegion() (above) returns null if
2777
                // there is no metadata for the region.
2778
                $metadata = $this->getMetadataForRegion($regionCode);
2779
                $nationalNumber = $this->getNationalSignificantNumber($number);
2780
                $formatRule = $this->chooseFormattingPatternForNumber($metadata->numberFormats(), $nationalNumber);
2781
                // The format rule could still be null here if the national number was 0 and there was no
2782
                // raw input (this should not be possible for numbers generated by the phonenumber library
2783
                // as they would also not have a country calling code and we would have exited earlier).
2784
                if ($formatRule === null) {
2785
                    $formattedNumber = $nationalFormat;
2786
                    break;
2787
                }
2788
                // When the format we apply to this number doesn't contain national prefix, we can just
2789
                // return the national format.
2790
                // TODO: Refactor the code below with the code in isNationalPrefixPresentIfRequired.
2791
                $candidateNationalPrefixRule = $formatRule->getNationalPrefixFormattingRule();
2792
                // We assume that the first-group symbol will never be _before_ the national prefix.
2793
                $indexOfFirstGroup = strpos($candidateNationalPrefixRule, '$1');
2794
                if ($indexOfFirstGroup <= 0) {
2795
                    $formattedNumber = $nationalFormat;
2796
                    break;
2797
                }
2798
                $candidateNationalPrefixRule = substr($candidateNationalPrefixRule, 0, $indexOfFirstGroup);
2799
                $candidateNationalPrefixRule = static::normalizeDigitsOnly($candidateNationalPrefixRule);
2800
                if (mb_strlen($candidateNationalPrefixRule) == 0) {
2801
                    // National prefix not used when formatting this number.
2802
                    $formattedNumber = $nationalFormat;
2803
                    break;
2804
                }
2805
                // Otherwise, we need to remove the national prefix from our output.
2806
                $numFormatCopy = new NumberFormat();
2807
                $numFormatCopy->mergeFrom($formatRule);
2808
                $numFormatCopy->clearNationalPrefixFormattingRule();
2809
                $numberFormats = array();
2810
                $numberFormats[] = $numFormatCopy;
2811
                $formattedNumber = $this->formatByPattern($number, PhoneNumberFormat::NATIONAL, $numberFormats);
2812
                break;
2813
        }
2814
        $rawInput = $number->getRawInput();
2815
        // If no digit is inserted/removed/modified as a result of our formatting, we return the
2816
        // formatted phone number; otherwise we return the raw input the user entered.
2817
        if ($formattedNumber !== null && mb_strlen($rawInput) > 0) {
2818
            $normalizedFormattedNumber = static::normalizeDiallableCharsOnly($formattedNumber);
2819
            $normalizedRawInput = static::normalizeDiallableCharsOnly($rawInput);
2820
            if ($normalizedFormattedNumber != $normalizedRawInput) {
2821
                $formattedNumber = $rawInput;
2822
            }
2823
        }
2824
        return $formattedNumber;
2825
    }
2826
2827
    /**
2828
     * Returns true if a number is from a region whose national significant number couldn't contain a
2829
     * leading zero, but has the italian_leading_zero field set to true.
2830
     * @param PhoneNumber $number
2831
     * @return bool
2832
     */
2833
    protected function hasUnexpectedItalianLeadingZero(PhoneNumber $number)
2834
    {
2835
        return $number->isItalianLeadingZero() && !$this->isLeadingZeroPossible($number->getCountryCode());
2836
    }
2837
2838
    /**
2839
     * Checks whether the country calling code is from a region whose national significant number
2840
     * could contain a leading zero. An example of such a region is Italy. Returns false if no
2841
     * metadata for the country is found.
2842
     * @param int $countryCallingCode
2843
     * @return bool
2844
     */
2845
    public function isLeadingZeroPossible($countryCallingCode)
2846
    {
2847
        $mainMetadataForCallingCode = $this->getMetadataForRegionOrCallingCode(
2848
            $countryCallingCode,
2849
            $this->getRegionCodeForCountryCode($countryCallingCode)
2850
        );
2851
        if ($mainMetadataForCallingCode === null) {
2852
            return false;
2853
        }
2854
        return (bool)$mainMetadataForCallingCode->isLeadingZeroPossible();
2855
    }
2856
2857
    /**
2858
     * @param PhoneNumber $number
2859
     * @return bool
2860
     */
2861
    protected function hasFormattingPatternForNumber(PhoneNumber $number)
2862
    {
2863
        $countryCallingCode = $number->getCountryCode();
2864
        $phoneNumberRegion = $this->getRegionCodeForCountryCode($countryCallingCode);
2865
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $phoneNumberRegion);
2866
        if ($metadata === null) {
2867
            return false;
2868
        }
2869
        $nationalNumber = $this->getNationalSignificantNumber($number);
2870
        $formatRule = $this->chooseFormattingPatternForNumber($metadata->numberFormats(), $nationalNumber);
2871
        return $formatRule !== null;
2872
    }
2873
2874
    /**
2875
     * Returns the national dialling prefix for a specific region. For example, this would be 1 for
2876
     * the United States, and 0 for New Zealand. Set stripNonDigits to true to strip symbols like "~"
2877
     * (which indicates a wait for a dialling tone) from the prefix returned. If no national prefix is
2878
     * present, we return null.
2879
     *
2880
     * <p>Warning: Do not use this method for do-your-own formatting - for some regions, the
2881
     * national dialling prefix is used only for certain types of numbers. Use the library's
2882
     * formatting functions to prefix the national prefix when required.
2883
     *
2884
     * @param string $regionCode the region that we want to get the dialling prefix for
2885
     * @param boolean $stripNonDigits true to strip non-digits from the national dialling prefix
2886
     * @return string the dialling prefix for the region denoted by regionCode
2887
     */
2888
    public function getNddPrefixForRegion($regionCode, $stripNonDigits)
2889
    {
2890
        $metadata = $this->getMetadataForRegion($regionCode);
2891
        if ($metadata === null) {
2892
            return null;
2893
        }
2894
        $nationalPrefix = $metadata->getNationalPrefix();
2895
        // If no national prefix was found, we return null.
2896
        if (mb_strlen($nationalPrefix) == 0) {
2897
            return null;
2898
        }
2899
        if ($stripNonDigits) {
2900
            // Note: if any other non-numeric symbols are ever used in national prefixes, these would have
2901
            // to be removed here as well.
2902
            $nationalPrefix = str_replace("~", "", $nationalPrefix);
2903
        }
2904
        return $nationalPrefix;
2905
    }
2906
2907
    /**
2908
     * Check if rawInput, which is assumed to be in the national format, has a national prefix. The
2909
     * national prefix is assumed to be in digits-only form.
2910
     * @param string $rawInput
2911
     * @param string $nationalPrefix
2912
     * @param string $regionCode
2913
     * @return bool
2914
     */
2915
    protected function rawInputContainsNationalPrefix($rawInput, $nationalPrefix, $regionCode)
2916
    {
2917
        $normalizedNationalNumber = static::normalizeDigitsOnly($rawInput);
2918
        if (strpos($normalizedNationalNumber, $nationalPrefix) === 0) {
2919
            try {
2920
                // Some Japanese numbers (e.g. 00777123) might be mistaken to contain the national prefix
2921
                // when written without it (e.g. 0777123) if we just do prefix matching. To tackle that, we
2922
                // check the validity of the number if the assumed national prefix is removed (777123 won't
2923
                // be valid in Japan).
2924
                return $this->isValidNumber(
2925
                    $this->parse(substr($normalizedNationalNumber, mb_strlen($nationalPrefix)), $regionCode)
2926
                );
2927
            } catch (NumberParseException $e) {
2928
                return false;
2929
            }
2930
        }
2931
        return false;
2932
    }
2933
2934
    /**
2935
     * Tests whether a phone number matches a valid pattern. Note this doesn't verify the number
2936
     * is actually in use, which is impossible to tell by just looking at a number itself. It only
2937
     * verifies whether the parsed, canonicalised number is valid: not whether a particular series of
2938
     * digits entered by the user is diallable from the region provided when parsing. For example, the
2939
     * number +41 (0) 78 927 2696 can be parsed into a number with country code "41" and national
2940
     * significant number "789272696". This is valid, while the original string is not diallable.
2941
     *
2942
     * @param PhoneNumber $number the phone number that we want to validate
2943
     * @return boolean that indicates whether the number is of a valid pattern
2944
     */
2945
    public function isValidNumber(PhoneNumber $number)
2946
    {
2947
        $regionCode = $this->getRegionCodeForNumber($number);
2948
        return $this->isValidNumberForRegion($number, $regionCode);
2949
    }
2950
2951
    /**
2952
     * Tests whether a phone number is valid for a certain region. Note this doesn't verify the number
2953
     * is actually in use, which is impossible to tell by just looking at a number itself. If the
2954
     * country calling code is not the same as the country calling code for the region, this
2955
     * immediately exits with false. After this, the specific number pattern rules for the region are
2956
     * examined. This is useful for determining for example whether a particular number is valid for
2957
     * Canada, rather than just a valid NANPA number.
2958
     * Warning: In most cases, you want to use {@link #isValidNumber} instead. For example, this
2959
     * method will mark numbers from British Crown dependencies such as the Isle of Man as invalid for
2960
     * the region "GB" (United Kingdom), since it has its own region code, "IM", which may be
2961
     * undesirable.
2962
     *
2963
     * @param PhoneNumber $number the phone number that we want to validate
2964
     * @param string $regionCode the region that we want to validate the phone number for
2965
     * @return boolean that indicates whether the number is of a valid pattern
2966
     */
2967
    public function isValidNumberForRegion(PhoneNumber $number, $regionCode)
2968
    {
2969
        $countryCode = $number->getCountryCode();
2970
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCode, $regionCode);
2971
        if (($metadata === null) ||
2972
            (static::REGION_CODE_FOR_NON_GEO_ENTITY !== $regionCode &&
2973
                $countryCode !== $this->getCountryCodeForValidRegion($regionCode))
2974
        ) {
2975
            // Either the region code was invalid, or the country calling code for this number does not
2976
            // match that of the region code.
2977
            return false;
2978
        }
2979
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
2980
2981
        return $this->getNumberTypeHelper($nationalSignificantNumber, $metadata) != PhoneNumberType::UNKNOWN;
2982
    }
2983
2984
    /**
2985
     * Parses a string and returns it as a phone number in proto buffer format. The method is quite
2986
     * lenient and looks for a number in the input text (raw input) and does not check whether the
2987
     * string is definitely only a phone number. To do this, it ignores punctuation and white-space,
2988
     * as well as any text before the number (e.g. a leading “Tel: ”) and trims the non-number bits.
2989
     * It will accept a number in any format (E164, national, international etc), assuming it can
2990
     * interpreted with the defaultRegion supplied. It also attempts to convert any alpha characters
2991
     * into digits if it thinks this is a vanity number of the type "1800 MICROSOFT".
2992
     *
2993
     * <p> This method will throw a {@link NumberParseException} if the number is not considered to
2994
     * be a possible number. Note that validation of whether the number is actually a valid number
2995
     * for a particular region is not performed. This can be done separately with {@link #isValidnumber}.
2996
     *
2997
     * @param string $numberToParse number that we are attempting to parse. This can contain formatting
2998
     *                          such as +, ( and -, as well as a phone number extension.
2999
     * @param string $defaultRegion region that we are expecting the number to be from. This is only used
3000
     *                          if the number being parsed is not written in international format.
3001
     *                          The country_code for the number in this case would be stored as that
3002
     *                          of the default region supplied. If the number is guaranteed to
3003
     *                          start with a '+' followed by the country calling code, then
3004
     *                          "ZZ" or null can be supplied.
3005
     * @param PhoneNumber|null $phoneNumber
3006
     * @param bool $keepRawInput
3007
     * @return PhoneNumber a phone number proto buffer filled with the parsed number
3008
     * @throws NumberParseException  if the string is not considered to be a viable phone number (e.g.
3009
     *                               too few or too many digits) or if no default region was supplied
3010
     *                               and the number is not in international format (does not start
3011
     *                               with +)
3012
     */
3013
    public function parse($numberToParse, $defaultRegion, PhoneNumber $phoneNumber = null, $keepRawInput = false)
3014
    {
3015
        if ($phoneNumber === null) {
3016
            $phoneNumber = new PhoneNumber();
3017
        }
3018
        $this->parseHelper($numberToParse, $defaultRegion, $keepRawInput, true, $phoneNumber);
3019
        return $phoneNumber;
3020
    }
3021
3022
    /**
3023
     * Formats a phone number in the specified format using client-defined formatting rules. Note that
3024
     * if the phone number has a country calling code of zero or an otherwise invalid country calling
3025
     * code, we cannot work out things like whether there should be a national prefix applied, or how
3026
     * to format extensions, so we return the national significant number with no formatting applied.
3027
     *
3028
     * @param PhoneNumber $number the phone number to be formatted
3029
     * @param int $numberFormat the format the phone number should be formatted into
3030
     * @param array $userDefinedFormats formatting rules specified by clients
3031
     * @return String the formatted phone number
3032
     */
3033
    public function formatByPattern(PhoneNumber $number, $numberFormat, array $userDefinedFormats)
3034
    {
3035
        $countryCallingCode = $number->getCountryCode();
3036
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
3037
        if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
3038
            return $nationalSignificantNumber;
3039
        }
3040
        // Note getRegionCodeForCountryCode() is used because formatting information for regions which
3041
        // share a country calling code is contained by only one region for performance reasons. For
3042
        // example, for NANPA regions it will be contained in the metadata for US.
3043
        $regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
3044
        // Metadata cannot be null because the country calling code is valid
3045
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode);
3046
3047
        $formattedNumber = "";
3048
3049
        $formattingPattern = $this->chooseFormattingPatternForNumber($userDefinedFormats, $nationalSignificantNumber);
3050
        if ($formattingPattern === null) {
3051
            // If no pattern above is matched, we format the number as a whole.
3052
            $formattedNumber .= $nationalSignificantNumber;
3053
        } else {
3054
            $numFormatCopy = new NumberFormat();
3055
            // Before we do a replacement of the national prefix pattern $NP with the national prefix, we
3056
            // need to copy the rule so that subsequent replacements for different numbers have the
3057
            // appropriate national prefix.
3058
            $numFormatCopy->mergeFrom($formattingPattern);
3059
            $nationalPrefixFormattingRule = $formattingPattern->getNationalPrefixFormattingRule();
3060
            if (mb_strlen($nationalPrefixFormattingRule) > 0) {
3061
                $nationalPrefix = $metadata->getNationalPrefix();
3062
                if (mb_strlen($nationalPrefix) > 0) {
3063
                    // Replace $NP with national prefix and $FG with the first group ($1).
3064
                    $npPatternMatcher = new Matcher(static::NP_PATTERN, $nationalPrefixFormattingRule);
3065
                    $nationalPrefixFormattingRule = $npPatternMatcher->replaceFirst($nationalPrefix);
3066
                    $fgPatternMatcher = new Matcher(static::FG_PATTERN, $nationalPrefixFormattingRule);
3067
                    $nationalPrefixFormattingRule = $fgPatternMatcher->replaceFirst("\\$1");
3068
                    $numFormatCopy->setNationalPrefixFormattingRule($nationalPrefixFormattingRule);
3069
                } else {
3070
                    // We don't want to have a rule for how to format the national prefix if there isn't one.
3071
                    $numFormatCopy->clearNationalPrefixFormattingRule();
3072
                }
3073
            }
3074
            $formattedNumber .= $this->formatNsnUsingPattern($nationalSignificantNumber, $numFormatCopy, $numberFormat);
3075
        }
3076
        $this->maybeAppendFormattedExtension($number, $metadata, $numberFormat, $formattedNumber);
3077
        $this->prefixNumberWithCountryCallingCode($countryCallingCode, $numberFormat, $formattedNumber);
3078
        return $formattedNumber;
3079
    }
3080
3081
    /**
3082
     * Gets a valid number for the specified region.
3083
     *
3084
     * @param string regionCode  the region for which an example number is needed
3085
     * @return PhoneNumber a valid fixed-line number for the specified region. Returns null when the metadata
3086
     *    does not contain such information, or the region 001 is passed in. For 001 (representing
3087
     *    non-geographical numbers), call {@link #getExampleNumberForNonGeoEntity} instead.
3088
     */
3089
    public function getExampleNumber($regionCode)
3090
    {
3091
        return $this->getExampleNumberForType($regionCode, PhoneNumberType::FIXED_LINE);
3092
    }
3093
3094
    /**
3095
     * Gets an invalid number for the specified region. This is useful for unit-testing purposes,
3096
     * where you want to test what will happen with an invalid number. Note that the number that is
3097
     * returned will always be able to be parsed and will have the correct country code. It may also
3098
     * be a valid *short* number/code for this region. Validity checking such numbers is handled with
3099
     * {@link ShortNumberInfo}.
3100
     *
3101
     * @param string $regionCode The region for which an example number is needed
3102
     * @return PhoneNumber|null An invalid number for the specified region. Returns null when an unsupported region
3103
     * or the region 001 (Earth) is passed in.
3104
     */
3105
    public function getInvalidExampleNumber($regionCode)
3106
    {
3107
        if (!$this->isValidRegionCode($regionCode)) {
3108
            return null;
3109
        }
3110
3111
        // We start off with a valid fixed-line number since every country supports this. Alternatively
3112
        // we could start with a different number type, since fixed-line numbers typically have a wide
3113
        // breadth of valid number lengths and we may have to make it very short before we get an
3114
        // invalid number.
3115
3116
        $desc = $this->getNumberDescByType($this->getMetadataForRegion($regionCode), PhoneNumberType::FIXED_LINE);
0 ignored issues
show
Bug introduced by
It seems like $this->getMetadataForRegion($regionCode) can be null; however, getNumberDescByType() does not accept null, maybe add an additional type check?

Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code:

/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
3117
3118
        if ($desc->getExampleNumber() == '') {
3119
            // This shouldn't happen; we have a test for this.
3120
            return null;
3121
        }
3122
3123
        $exampleNumber = $desc->getExampleNumber();
3124
3125
        // Try and make the number invalid. We do this by changing the length. We try reducing the
3126
        // length of the number, since currently no region has a number that is the same length as
3127
        // MIN_LENGTH_FOR_NSN. This is probably quicker than making the number longer, which is another
3128
        // alternative. We could also use the possible number pattern to extract the possible lengths of
3129
        // the number to make this faster, but this method is only for unit-testing so simplicity is
3130
        // preferred to performance.  We don't want to return a number that can't be parsed, so we check
3131
        // the number is long enough. We try all possible lengths because phone number plans often have
3132
        // overlapping prefixes so the number 123456 might be valid as a fixed-line number, and 12345 as
3133
        // a mobile number. It would be faster to loop in a different order, but we prefer numbers that
3134
        // look closer to real numbers (and it gives us a variety of different lengths for the resulting
3135
        // phone numbers - otherwise they would all be MIN_LENGTH_FOR_NSN digits long.)
3136
        for ($phoneNumberLength = mb_strlen($exampleNumber) - 1; $phoneNumberLength >= static::MIN_LENGTH_FOR_NSN; $phoneNumberLength--) {
3137
            $numberToTry = mb_substr($exampleNumber, 0, $phoneNumberLength);
3138
            try {
3139
                $possiblyValidNumber = $this->parse($numberToTry, $regionCode);
3140
                if (!$this->isValidNumber($possiblyValidNumber)) {
3141
                    return $possiblyValidNumber;
3142
                }
3143
            } catch (NumberParseException $e) {
3144
                // Shouldn't happen: we have already checked the length, we know example numbers have
3145
                // only valid digits, and we know the region code is fine.
3146
            }
3147
        }
3148
        // We have a test to check that this doesn't happen for any of our supported regions.
3149
        return null;
3150
    }
3151
3152
    /**
3153
     * Gets a valid number for the specified region and number type.
3154
     *
3155
     * @param string|int $regionCodeOrType the region for which an example number is needed
3156
     * @param int $type the PhoneNumberType of number that is needed
3157
     * @return PhoneNumber a valid number for the specified region and type. Returns null when the metadata
3158
     *     does not contain such information or if an invalid region or region 001 was entered.
3159
     *     For 001 (representing non-geographical numbers), call
3160
     *     {@link #getExampleNumberForNonGeoEntity} instead.
3161
     *
3162
     * If $regionCodeOrType is the only parameter supplied, then a valid number for the specified number type
3163
     * will be returned that may belong to any country.
3164
     */
3165
    public function getExampleNumberForType($regionCodeOrType, $type = null)
3166
    {
3167
        if ($regionCodeOrType !== null && $type === null) {
3168
            /*
3169
             * Gets a valid number for the specified number type (it may belong to any country).
3170
             */
3171
            foreach ($this->getSupportedRegions() as $regionCode) {
3172
                $exampleNumber = $this->getExampleNumberForType($regionCode, $regionCodeOrType);
3173
                if ($exampleNumber !== null) {
3174
                    return $exampleNumber;
3175
                }
3176
            }
3177
3178
            // If there wasn't an example number for a region, try the non-geographical entities
3179
            foreach ($this->getSupportedGlobalNetworkCallingCodes() as $countryCallingCode) {
3180
                $desc = $this->getNumberDescByType($this->getMetadataForNonGeographicalRegion($countryCallingCode), $regionCodeOrType);
0 ignored issues
show
Bug introduced by
It seems like $this->getMetadataForNon...on($countryCallingCode) can be null; however, getNumberDescByType() does not accept null, maybe add an additional type check?

Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code:

/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
3181
                try {
3182
                    if ($desc->getExampleNumber() != '') {
3183
                        return $this->parse("+" . $countryCallingCode . $desc->getExampleNumber(), static::UNKNOWN_REGION);
3184
                    }
3185
                } catch (NumberParseException $e) {
3186
                    // noop
3187
                }
3188
            }
3189
            // There are no example numbers of this type for any country in the library.
3190
            return null;
3191
        }
3192
3193
        // Check the region code is valid.
3194
        if (!$this->isValidRegionCode($regionCodeOrType)) {
3195
            return null;
3196
        }
3197
        $desc = $this->getNumberDescByType($this->getMetadataForRegion($regionCodeOrType), $type);
0 ignored issues
show
Bug introduced by
It seems like $this->getMetadataForRegion($regionCodeOrType) can be null; however, getNumberDescByType() does not accept null, maybe add an additional type check?

Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code:

/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
3198
        try {
3199
            if ($desc->hasExampleNumber()) {
3200
                return $this->parse($desc->getExampleNumber(), $regionCodeOrType);
3201
            }
3202
        } catch (NumberParseException $e) {
3203
            // noop
3204
        }
3205
        return null;
3206
    }
3207
3208
    /**
3209
     * @param PhoneMetadata $metadata
3210
     * @param int $type PhoneNumberType
3211
     * @return PhoneNumberDesc
3212
     */
3213
    protected function getNumberDescByType(PhoneMetadata $metadata, $type)
3214
    {
3215
        switch ($type) {
3216
            case PhoneNumberType::PREMIUM_RATE:
3217
                return $metadata->getPremiumRate();
3218
            case PhoneNumberType::TOLL_FREE:
3219
                return $metadata->getTollFree();
3220
            case PhoneNumberType::MOBILE:
3221
                return $metadata->getMobile();
3222
            case PhoneNumberType::FIXED_LINE:
3223
            case PhoneNumberType::FIXED_LINE_OR_MOBILE:
3224
                return $metadata->getFixedLine();
3225
            case PhoneNumberType::SHARED_COST:
3226
                return $metadata->getSharedCost();
3227
            case PhoneNumberType::VOIP:
3228
                return $metadata->getVoip();
3229
            case PhoneNumberType::PERSONAL_NUMBER:
3230
                return $metadata->getPersonalNumber();
3231
            case PhoneNumberType::PAGER:
3232
                return $metadata->getPager();
3233
            case PhoneNumberType::UAN:
3234
                return $metadata->getUan();
3235
            case PhoneNumberType::VOICEMAIL:
3236
                return $metadata->getVoicemail();
3237
            default:
3238
                return $metadata->getGeneralDesc();
3239
        }
3240
    }
3241
3242
    /**
3243
     * Gets a valid number for the specified country calling code for a non-geographical entity.
3244
     *
3245
     * @param int $countryCallingCode the country calling code for a non-geographical entity
3246
     * @return PhoneNumber a valid number for the non-geographical entity. Returns null when the metadata
3247
     *    does not contain such information, or the country calling code passed in does not belong
3248
     *    to a non-geographical entity.
3249
     */
3250
    public function getExampleNumberForNonGeoEntity($countryCallingCode)
3251
    {
3252
        $metadata = $this->getMetadataForNonGeographicalRegion($countryCallingCode);
3253
        if ($metadata !== null) {
3254
            // For geographical entities, fixed-line data is always present. However, for non-geographical
3255
            // entities, this is not the case, so we have to go through different types to find the
3256
            // example number. We don't check fixed-line or personal number since they aren't used by
3257
            // non-geographical entities (if this changes, a unit-test will catch this.)
3258
            /** @var PhoneNumberDesc[] $list */
3259
            $list = array(
3260
                $metadata->getMobile(),
3261
                $metadata->getTollFree(),
3262
                $metadata->getSharedCost(),
3263
                $metadata->getVoip(),
3264
                $metadata->getVoicemail(),
3265
                $metadata->getUan(),
3266
                $metadata->getPremiumRate(),
3267
            );
3268
            foreach ($list as $desc) {
3269
                try {
3270
                    if ($desc !== null && $desc->hasExampleNumber()) {
3271
                        return $this->parse('+' . $countryCallingCode . $desc->getExampleNumber(), self::UNKNOWN_REGION);
3272
                    }
3273
                } catch (NumberParseException $e) {
3274
                    // noop
3275
                }
3276
            }
3277
        }
3278
        return null;
3279
    }
3280
3281
3282
    /**
3283
     * Takes two phone numbers and compares them for equality.
3284
     *
3285
     * <p>Returns EXACT_MATCH if the country_code, NSN, presence of a leading zero
3286
     * for Italian numbers and any extension present are the same. Returns NSN_MATCH
3287
     * if either or both has no region specified, and the NSNs and extensions are
3288
     * the same. Returns SHORT_NSN_MATCH if either or both has no region specified,
3289
     * or the region specified is the same, and one NSN could be a shorter version
3290
     * of the other number. This includes the case where one has an extension
3291
     * specified, and the other does not. Returns NO_MATCH otherwise. For example,
3292
     * the numbers +1 345 657 1234 and 657 1234 are a SHORT_NSN_MATCH. The numbers
3293
     * +1 345 657 1234 and 345 657 are a NO_MATCH.
3294
     *
3295
     * @param $firstNumberIn PhoneNumber|string First number to compare. If it is a
3296
     * string it can contain formatting, and can have country calling code specified
3297
     * with + at the start.
3298
     * @param $secondNumberIn PhoneNumber|string Second number to compare. If it is a
3299
     * string it can contain formatting, and can have country calling code specified
3300
     * with + at the start.
3301
     * @throws \InvalidArgumentException
3302
     * @return int {MatchType} NOT_A_NUMBER, NO_MATCH,
3303
     */
3304
    public function isNumberMatch($firstNumberIn, $secondNumberIn)
3305
    {
3306
        if (is_string($firstNumberIn) && is_string($secondNumberIn)) {
3307
            try {
3308
                $firstNumberAsProto = $this->parse($firstNumberIn, static::UNKNOWN_REGION);
3309
                return $this->isNumberMatch($firstNumberAsProto, $secondNumberIn);
3310
            } catch (NumberParseException $e) {
3311
                if ($e->getErrorType() === NumberParseException::INVALID_COUNTRY_CODE) {
3312
                    try {
3313
                        $secondNumberAsProto = $this->parse($secondNumberIn, static::UNKNOWN_REGION);
3314
                        return $this->isNumberMatch($secondNumberAsProto, $firstNumberIn);
3315
                    } catch (NumberParseException $e2) {
3316
                        if ($e2->getErrorType() === NumberParseException::INVALID_COUNTRY_CODE) {
3317
                            try {
3318
                                $firstNumberProto = new PhoneNumber();
3319
                                $secondNumberProto = new PhoneNumber();
3320
                                $this->parseHelper($firstNumberIn, null, false, false, $firstNumberProto);
3321
                                $this->parseHelper($secondNumberIn, null, false, false, $secondNumberProto);
3322
                                return $this->isNumberMatch($firstNumberProto, $secondNumberProto);
3323
                            } catch (NumberParseException $e3) {
3324
                                // Fall through and return MatchType::NOT_A_NUMBER
3325
                            }
3326
                        }
3327
                    }
3328
                }
3329
            }
3330
            return MatchType::NOT_A_NUMBER;
3331
        }
3332
        if ($firstNumberIn instanceof PhoneNumber && is_string($secondNumberIn)) {
3333
            // First see if the second number has an implicit country calling code, by attempting to parse
3334
            // it.
3335
            try {
3336
                $secondNumberAsProto = $this->parse($secondNumberIn, static::UNKNOWN_REGION);
3337
                return $this->isNumberMatch($firstNumberIn, $secondNumberAsProto);
3338
            } catch (NumberParseException $e) {
3339
                if ($e->getErrorType() === NumberParseException::INVALID_COUNTRY_CODE) {
3340
                    // The second number has no country calling code. EXACT_MATCH is no longer possible.
3341
                    // We parse it as if the region was the same as that for the first number, and if
3342
                    // EXACT_MATCH is returned, we replace this with NSN_MATCH.
3343
                    $firstNumberRegion = $this->getRegionCodeForCountryCode($firstNumberIn->getCountryCode());
3344
                    try {
3345
                        if ($firstNumberRegion != static::UNKNOWN_REGION) {
3346
                            $secondNumberWithFirstNumberRegion = $this->parse($secondNumberIn, $firstNumberRegion);
3347
                            $match = $this->isNumberMatch($firstNumberIn, $secondNumberWithFirstNumberRegion);
3348
                            if ($match === MatchType::EXACT_MATCH) {
3349
                                return MatchType::NSN_MATCH;
3350
                            }
3351
                            return $match;
3352
                        } else {
3353
                            // If the first number didn't have a valid country calling code, then we parse the
3354
                            // second number without one as well.
3355
                            $secondNumberProto = new PhoneNumber();
3356
                            $this->parseHelper($secondNumberIn, null, false, false, $secondNumberProto);
3357
                            return $this->isNumberMatch($firstNumberIn, $secondNumberProto);
3358
                        }
3359
                    } catch (NumberParseException $e2) {
3360
                        // Fall-through to return NOT_A_NUMBER.
3361
                    }
3362
                }
3363
            }
3364
        }
3365
        if ($firstNumberIn instanceof PhoneNumber && $secondNumberIn instanceof PhoneNumber) {
3366
            // We only care about the fields that uniquely define a number, so we copy these across
3367
            // explicitly.
3368
            $firstNumber = self::copyCoreFieldsOnly($firstNumberIn);
3369
            $secondNumber = self::copyCoreFieldsOnly($secondNumberIn);
3370
3371
            // Early exit if both had extensions and these are different.
3372
            if ($firstNumber->hasExtension() && $secondNumber->hasExtension() &&
3373
                $firstNumber->getExtension() != $secondNumber->getExtension()
3374
            ) {
3375
                return MatchType::NO_MATCH;
3376
            }
3377
3378
            $firstNumberCountryCode = $firstNumber->getCountryCode();
3379
            $secondNumberCountryCode = $secondNumber->getCountryCode();
3380
            // Both had country_code specified.
3381
            if ($firstNumberCountryCode != 0 && $secondNumberCountryCode != 0) {
0 ignored issues
show
Bug introduced by
It seems like you are loosely comparing $firstNumberCountryCode of type integer|null to 0; this is ambiguous as not only 0 == 0 is true, but null == 0 is true, too. Consider using a strict comparison ===.
Loading history...
Bug introduced by
It seems like you are loosely comparing $secondNumberCountryCode of type integer|null to 0; this is ambiguous as not only 0 == 0 is true, but null == 0 is true, too. Consider using a strict comparison ===.
Loading history...
3382
                if ($firstNumber->equals($secondNumber)) {
3383
                    return MatchType::EXACT_MATCH;
3384
                } elseif ($firstNumberCountryCode == $secondNumberCountryCode &&
3385
                    $this->isNationalNumberSuffixOfTheOther($firstNumber, $secondNumber)
3386
                ) {
3387
                    // A SHORT_NSN_MATCH occurs if there is a difference because of the presence or absence of
3388
                    // an 'Italian leading zero', the presence or absence of an extension, or one NSN being a
3389
                    // shorter variant of the other.
3390
                    return MatchType::SHORT_NSN_MATCH;
3391
                }
3392
                // This is not a match.
3393
                return MatchType::NO_MATCH;
3394
            }
3395
            // Checks cases where one or both country_code fields were not specified. To make equality
3396
            // checks easier, we first set the country_code fields to be equal.
3397
            $firstNumber->setCountryCode($secondNumberCountryCode);
3398
            // If all else was the same, then this is an NSN_MATCH.
3399
            if ($firstNumber->equals($secondNumber)) {
3400
                return MatchType::NSN_MATCH;
3401
            }
3402
            if ($this->isNationalNumberSuffixOfTheOther($firstNumber, $secondNumber)) {
3403
                return MatchType::SHORT_NSN_MATCH;
3404
            }
3405
            return MatchType::NO_MATCH;
3406
        }
3407
        return MatchType::NOT_A_NUMBER;
3408
    }
3409
3410
    /**
3411
     * Returns true when one national number is the suffix of the other or both are the same.
3412
     * @param PhoneNumber $firstNumber
3413
     * @param PhoneNumber $secondNumber
3414
     * @return bool
3415
     */
3416
    protected function isNationalNumberSuffixOfTheOther(PhoneNumber $firstNumber, PhoneNumber $secondNumber)
3417
    {
3418
        $firstNumberNationalNumber = trim((string)$firstNumber->getNationalNumber());
3419
        $secondNumberNationalNumber = trim((string)$secondNumber->getNationalNumber());
3420
        return $this->stringEndsWithString($firstNumberNationalNumber, $secondNumberNationalNumber) ||
3421
        $this->stringEndsWithString($secondNumberNationalNumber, $firstNumberNationalNumber);
3422
    }
3423
3424
    protected function stringEndsWithString($hayStack, $needle)
3425
    {
3426
        $revNeedle = strrev($needle);
3427
        $revHayStack = strrev($hayStack);
3428
        return strpos($revHayStack, $revNeedle) === 0;
3429
    }
3430
3431
    /**
3432
     * Returns true if the supplied region supports mobile number portability. Returns false for
3433
     * invalid, unknown or regions that don't support mobile number portability.
3434
     *
3435
     * @param string $regionCode the region for which we want to know whether it supports mobile number
3436
     *                    portability or not.
3437
     * @return bool
3438
     */
3439
    public function isMobileNumberPortableRegion($regionCode)
3440
    {
3441
        $metadata = $this->getMetadataForRegion($regionCode);
3442
        if ($metadata === null) {
3443
            return false;
3444
        }
3445
3446
        return $metadata->isMobileNumberPortableRegion();
3447
    }
3448
3449
    /**
3450
     * Check whether a phone number is a possible number given a number in the form of a string, and
3451
     * the region where the number could be dialed from. It provides a more lenient check than
3452
     * {@link #isValidNumber}. See {@link #isPossibleNumber(PhoneNumber)} for details.
3453
     *
3454
     * <p>This method first parses the number, then invokes {@link #isPossibleNumber(PhoneNumber)}
3455
     * with the resultant PhoneNumber object.
3456
     *
3457
     * @param PhoneNumber|string $number the number that needs to be checked, in the form of a string
3458
     * @param string $regionDialingFrom the region that we are expecting the number to be dialed from.
3459
     *     Note this is different from the region where the number belongs.  For example, the number
3460
     *     +1 650 253 0000 is a number that belongs to US. When written in this form, it can be
3461
     *     dialed from any region. When it is written as 00 1 650 253 0000, it can be dialed from any
3462
     *     region which uses an international dialling prefix of 00. When it is written as
3463
     *     650 253 0000, it can only be dialed from within the US, and when written as 253 0000, it
3464
     *     can only be dialed from within a smaller area in the US (Mountain View, CA, to be more
3465
     *     specific).
3466
     * @return boolean true if the number is possible
3467
     */
3468
    public function isPossibleNumber($number, $regionDialingFrom = null)
3469
    {
3470
        if ($regionDialingFrom !== null && is_string($number)) {
3471
            try {
3472
                return $this->isPossibleNumberWithReason(
3473
                    $this->parse($number, $regionDialingFrom)
3474
                ) === ValidationResult::IS_POSSIBLE;
3475
            } catch (NumberParseException $e) {
3476
                return false;
3477
            }
3478
        } else {
3479
            return $this->isPossibleNumberWithReason($number) === ValidationResult::IS_POSSIBLE;
0 ignored issues
show
Bug introduced by
It seems like $number defined by parameter $number on line 3468 can also be of type string; however, libphonenumber\PhoneNumb...sibleNumberWithReason() does only seem to accept object<libphonenumber\PhoneNumber>, maybe add an additional type check?

This check looks at variables that have been passed in as parameters and are passed out again to other methods.

If the outgoing method call has stricter type requirements than the method itself, an issue is raised.

An additional type check may prevent trouble.

Loading history...
3480
        }
3481
    }
3482
3483
3484
    /**
3485
     * Check whether a phone number is a possible number. It provides a more lenient check than
3486
     * {@link #isValidNumber} in the following sense:
3487
     * <ol>
3488
     * <li> It only checks the length of phone numbers. In particular, it doesn't check starting
3489
     *      digits of the number.
3490
     * <li> It doesn't attempt to figure out the type of the number, but uses general rules which
3491
     *      applies to all types of phone numbers in a region. Therefore, it is much faster than
3492
     *      isValidNumber.
3493
     * <li> For fixed line numbers, many regions have the concept of area code, which together with
3494
     *      subscriber number constitute the national significant number. It is sometimes okay to dial
3495
     *      only the subscriber number when dialing in the same area. This function will return
3496
     *      true if the subscriber-number-only version is passed in. On the other hand, because
3497
     *      isValidNumber validates using information on both starting digits (for fixed line
3498
     *      numbers, that would most likely be area codes) and length (obviously includes the
3499
     *      length of area codes for fixed line numbers), it will return false for the
3500
     *      subscriber-number-only version.
3501
     * </ol>
3502
     * @param PhoneNumber $number the number that needs to be checked
3503
     * @return int a ValidationResult object which indicates whether the number is possible
3504
     */
3505
    public function isPossibleNumberWithReason(PhoneNumber $number)
3506
    {
3507
        return $this->isPossibleNumberForTypeWithReason($number, PhoneNumberType::UNKNOWN);
3508
    }
3509
3510
   /**
3511
    * Check whether a phone number is a possible number of a particular type. For types that don't
3512
    * exist in a particular region, this will return a result that isn't so useful; it is recommended
3513
    * that you use {@link #getSupportedTypesForRegion} or {@link #getSupportedTypesForNonGeoEntity}
3514
    * respectively before calling this method to determine whether you should call it for this number
3515
    * at all.
3516
    *
3517
    * This provides a more lenient check than {@link #isValidNumber} in the following sense:
3518
    *
3519
    * <ol>
3520
    *   <li> It only checks the length of phone numbers. In particular, it doesn't check starting
3521
    *       digits of the number.
3522
    *   <li> For fixed line numbers, many regions have the concept of area code, which together with
3523
    *       subscriber number constitute the national significant number. It is sometimes okay to
3524
    *       dial the subscriber number only when dialing in the same area. This function will return
3525
    *       true if the subscriber-number-only version is passed in. On the other hand, because
3526
    *       isValidNumber validates using information on both starting digits (for fixed line
3527
    *       numbers, that would most likely be area codes) and length (obviously includes the length
3528
    *       of area codes for fixed line numbers), it will return false for the
3529
    *       subscriber-number-only version.
3530
    * </ol>
3531
    *
3532
    * @param PhoneNumber $number the number that needs to be checked
3533
    * @param int $type the PhoneNumberType we are interested in
3534
    * @return int a ValidationResult object which indicates whether the number is possible
3535
    */
3536
    public function isPossibleNumberForTypeWithReason(PhoneNumber $number, $type)
3537
    {
3538
        $nationalNumber = $this->getNationalSignificantNumber($number);
3539
        $countryCode = $number->getCountryCode();
3540
3541
        // Note: For regions that share a country calling code, like NANPA numbers, we just use the
3542
        // rules from the default region (US in this case) since the getRegionCodeForNumber will not
3543
        // work if the number is possible but not valid. There is in fact one country calling code (290)
3544
        // where the possible number pattern differs between various regions (Saint Helena and Tristan
3545
        // da Cuñha), but this is handled by putting all possible lengths for any country with this
3546
        // country calling code in the metadata for the default region in this case.
3547
        if (!$this->hasValidCountryCallingCode($countryCode)) {
3548
            return ValidationResult::INVALID_COUNTRY_CODE;
3549
        }
3550
3551
        $regionCode = $this->getRegionCodeForCountryCode($countryCode);
3552
        // Metadata cannot be null because the country calling code is valid.
3553
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCode, $regionCode);
3554
        return $this->testNumberLength($nationalNumber, $metadata, $type);
0 ignored issues
show
Bug introduced by
It seems like $metadata defined by $this->getMetadataForReg...untryCode, $regionCode) on line 3553 can be null; however, libphonenumber\PhoneNumberUtil::testNumberLength() does not accept null, maybe add an additional type check?

Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code:

/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
3555
    }
3556
3557
    /**
3558
     * Attempts to extract a valid number from a phone number that is too long to be valid, and resets
3559
     * the PhoneNumber object passed in to that valid version. If no valid number could be extracted,
3560
     * the PhoneNumber object passed in will not be modified.
3561
     * @param PhoneNumber $number a PhoneNumber object which contains a number that is too long to be valid.
3562
     * @return boolean true if a valid phone number can be successfully extracted.
3563
     */
3564
    public function truncateTooLongNumber(PhoneNumber $number)
3565
    {
3566
        if ($this->isValidNumber($number)) {
3567
            return true;
3568
        }
3569
        $numberCopy = new PhoneNumber();
3570
        $numberCopy->mergeFrom($number);
3571
        $nationalNumber = $number->getNationalNumber();
3572
        do {
3573
            $nationalNumber = floor($nationalNumber / 10);
3574
            $numberCopy->setNationalNumber($nationalNumber);
3575
            if ($this->isPossibleNumberWithReason($numberCopy) == ValidationResult::TOO_SHORT || $nationalNumber == 0) {
3576
                return false;
3577
            }
3578
        } while (!$this->isValidNumber($numberCopy));
3579
        $number->setNationalNumber($nationalNumber);
3580
        return true;
3581
    }
3582
}
3583