Passed
Push — upstream-8.11.0 ( 4431ea )
by Joshua
03:25
created

PhoneNumberUtil::isNumberMatch()   F

Complexity

Conditions 27
Paths 144

Size

Total Lines 105
Code Lines 59

Duplication

Lines 0
Ratio 0 %

Code Coverage

Tests 53
CRAP Score 28.1586

Importance

Changes 1
Bugs 0 Features 0
Metric Value
cc 27
eloc 59
c 1
b 0
f 0
nc 144
nop 2
dl 0
loc 105
ccs 53
cts 60
cp 0.8833
crap 28.1586
rs 3.8

How to fix   Long Method    Complexity   

Long Method

Small methods make your code easier to understand, in particular if combined with a good name. Besides, if your method is small, finding a good name is usually much easier.

For example, if you find yourself adding comments to a method's body, this is usually a good sign to extract the commented part to a new method, and use the comment as a starting point when coming up with a good name for this new method.

Commonly applied refactorings include:

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/google/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, used to find numbers in
75
    // text and to decide what is a viable phone number. This excludes diallable characters.
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 single international dialing
84
    // prefix or not. If a region has a single international prefix (e.g. 011 in USA), it will be
85
    // represented as a string that contains a sequence of ASCII digits, and possible a tilde, which
86
    // signals waiting for the tone. If there are multiple available international prefixes in a
87
    // region, they will be represented as a regex string that always contains one or more characters
88
    // that are not ASCII digits or a tilde.
89
    const SINGLE_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
    // Constants used in the formatting rules to represent the national prefix, first group and
98
    // carrier code respectively.
99
    const NP_STRING = '$NP';
100
    const FG_STRING = '$FG';
101
    const CC_STRING = '$CC';
102
103
    // A pattern that is used to determine if the national prefix formatting rule has the first group
104
    // only, i.e., does not start with the national prefix. Note that the pattern explicitly allows
105
    // for unbalanced parentheses.
106
    const FIRST_GROUP_ONLY_PREFIX_PATTERN = '\\(?\\$1\\)?';
107
    public static $PLUS_CHARS_PATTERN;
108
    protected static $SEPARATOR_PATTERN;
109
    protected static $CAPTURING_DIGIT_PATTERN;
110
    protected static $VALID_START_CHAR_PATTERN;
111
    public static $SECOND_NUMBER_START_PATTERN = '[\\\\/] *x';
112
    public static $UNWANTED_END_CHAR_PATTERN = "[[\\P{N}&&\\P{L}]&&[^#]]+$";
113
    protected static $DIALLABLE_CHAR_MAPPINGS = array();
114
    protected static $CAPTURING_EXTN_DIGITS;
115
116
    /**
117
     * @var PhoneNumberUtil
118
     */
119
    protected static $instance;
120
121
    /**
122
     * Only upper-case variants of alpha characters are stored.
123
     * @var array
124
     */
125
    protected static $ALPHA_MAPPINGS = array(
126
        'A' => '2',
127
        'B' => '2',
128
        'C' => '2',
129
        'D' => '3',
130
        'E' => '3',
131
        'F' => '3',
132
        'G' => '4',
133
        'H' => '4',
134
        'I' => '4',
135
        'J' => '5',
136
        'K' => '5',
137
        'L' => '5',
138
        'M' => '6',
139
        'N' => '6',
140
        'O' => '6',
141
        'P' => '7',
142
        'Q' => '7',
143
        'R' => '7',
144
        'S' => '7',
145
        'T' => '8',
146
        'U' => '8',
147
        'V' => '8',
148
        'W' => '9',
149
        'X' => '9',
150
        'Y' => '9',
151
        'Z' => '9',
152
    );
153
154
    /**
155
     * Map of country calling codes that use a mobile token before the area code. One example of when
156
     * this is relevant is when determining the length of the national destination code, which should
157
     * be the length of the area code plus the length of the mobile token.
158
     * @var array
159
     */
160
    protected static $MOBILE_TOKEN_MAPPINGS = array();
161
162
    /**
163
     * Set of country codes that have geographically assigned mobile numbers (see GEO_MOBILE_COUNTRIES
164
     * below) which are not based on *area codes*. For example, in China mobile numbers start with a
165
     * carrier indicator, and beyond that are geographically assigned: this carrier indicator is not
166
     * considered to be an area code.
167
     *
168
     * @var array
169
     */
170
    protected static $GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES;
171
172
    /**
173
     * Set of country calling codes that have geographically assigned mobile numbers. This may not be
174
     * complete; we add calling codes case by case, as we find geographical mobile numbers or hear
175
     * from user reports. Note that countries like the US, where we can't distinguish between
176
     * fixed-line or mobile numbers, are not listed here, since we consider FIXED_LINE_OR_MOBILE to be
177
     * a possibly geographically-related type anyway (like FIXED_LINE).
178
     *
179
     * @var array
180
     */
181
    protected static $GEO_MOBILE_COUNTRIES;
182
183
    /**
184
     * For performance reasons, amalgamate both into one map.
185
     * @var array
186
     */
187
    protected static $ALPHA_PHONE_MAPPINGS;
188
189
    /**
190
     * Separate map of all symbols that we wish to retain when formatting alpha numbers. This
191
     * includes digits, ASCII letters and number grouping symbols such as "-" and " ".
192
     * @var array
193
     */
194
    protected static $ALL_PLUS_NUMBER_GROUPING_SYMBOLS;
195
196
    /**
197
     * Simple ASCII digits map used to populate ALPHA_PHONE_MAPPINGS and
198
     * ALL_PLUS_NUMBER_GROUPING_SYMBOLS.
199
     * @var array
200
     */
201
    protected static $asciiDigitMappings = array(
202
        '0' => '0',
203
        '1' => '1',
204
        '2' => '2',
205
        '3' => '3',
206
        '4' => '4',
207
        '5' => '5',
208
        '6' => '6',
209
        '7' => '7',
210
        '8' => '8',
211
        '9' => '9',
212
    );
213
214
    /**
215
     * Regexp of all possible ways to write extensions, for use when parsing. This will be run as a
216
     * case-insensitive regexp match. Wide character versions are also provided after each ASCII
217
     * version.
218
     * @var String
219
     */
220
    protected static $EXTN_PATTERNS_FOR_PARSING;
221
    /**
222
     * @var string
223
     * @internal
224
     */
225
    public static $EXTN_PATTERNS_FOR_MATCHING;
226
    protected static $EXTN_PATTERN;
227
    protected static $VALID_PHONE_NUMBER_PATTERN;
228
    protected static $MIN_LENGTH_PHONE_NUMBER_PATTERN;
229
    /**
230
     *  Regular expression of viable phone numbers. This is location independent. Checks we have at
231
     * least three leading digits, and only valid punctuation, alpha characters and
232
     * digits in the phone number. Does not include extension data.
233
     * The symbol 'x' is allowed here as valid punctuation since it is often used as a placeholder for
234
     * carrier codes, for example in Brazilian phone numbers. We also allow multiple "+" characters at
235
     * the start.
236
     * Corresponds to the following:
237
     * [digits]{minLengthNsn}|
238
     * plus_sign*(([punctuation]|[star])*[digits]){3,}([punctuation]|[star]|[digits]|[alpha])*
239
     *
240
     * The first reg-ex is to allow short numbers (two digits long) to be parsed if they are entered
241
     * as "15" etc, but only if there is no punctuation in them. The second expression restricts the
242
     * number of digits to three or more, but then allows them to be in international form, and to
243
     * have alpha-characters and punctuation.
244
     *
245
     * Note VALID_PUNCTUATION starts with a -, so must be the first in the range.
246
     * @var string
247
     */
248
    protected static $VALID_PHONE_NUMBER;
249
    protected static $numericCharacters = array(
250
        "\xef\xbc\x90" => 0,
251
        "\xef\xbc\x91" => 1,
252
        "\xef\xbc\x92" => 2,
253
        "\xef\xbc\x93" => 3,
254
        "\xef\xbc\x94" => 4,
255
        "\xef\xbc\x95" => 5,
256
        "\xef\xbc\x96" => 6,
257
        "\xef\xbc\x97" => 7,
258
        "\xef\xbc\x98" => 8,
259
        "\xef\xbc\x99" => 9,
260
261
        "\xd9\xa0" => 0,
262
        "\xd9\xa1" => 1,
263
        "\xd9\xa2" => 2,
264
        "\xd9\xa3" => 3,
265
        "\xd9\xa4" => 4,
266
        "\xd9\xa5" => 5,
267
        "\xd9\xa6" => 6,
268
        "\xd9\xa7" => 7,
269
        "\xd9\xa8" => 8,
270
        "\xd9\xa9" => 9,
271
272
        "\xdb\xb0" => 0,
273
        "\xdb\xb1" => 1,
274
        "\xdb\xb2" => 2,
275
        "\xdb\xb3" => 3,
276
        "\xdb\xb4" => 4,
277
        "\xdb\xb5" => 5,
278
        "\xdb\xb6" => 6,
279
        "\xdb\xb7" => 7,
280
        "\xdb\xb8" => 8,
281
        "\xdb\xb9" => 9,
282
283
        "\xe1\xa0\x90" => 0,
284
        "\xe1\xa0\x91" => 1,
285
        "\xe1\xa0\x92" => 2,
286
        "\xe1\xa0\x93" => 3,
287
        "\xe1\xa0\x94" => 4,
288
        "\xe1\xa0\x95" => 5,
289
        "\xe1\xa0\x96" => 6,
290
        "\xe1\xa0\x97" => 7,
291
        "\xe1\xa0\x98" => 8,
292
        "\xe1\xa0\x99" => 9,
293
    );
294
295
    /**
296
     * The set of county calling codes that map to the non-geo entity region ("001").
297
     * @var array
298
     */
299
    protected $countryCodesForNonGeographicalRegion = array();
300
    /**
301
     * The set of regions the library supports.
302
     * @var array
303
     */
304
    protected $supportedRegions = array();
305
306
    /**
307
     * A mapping from a country calling code to the region codes which denote the region represented
308
     * by that country calling code. In the case of multiple regions sharing a calling code, such as
309
     * the NANPA regions, the one indicated with "isMainCountryForCode" in the metadata should be
310
     * first.
311
     * @var array
312
     */
313
    protected $countryCallingCodeToRegionCodeMap = array();
314
    /**
315
     * The set of regions that share country calling code 1.
316
     * @var array
317
     */
318
    protected $nanpaRegions = array();
319
320
    /**
321
     * @var MetadataSourceInterface
322
     */
323
    protected $metadataSource;
324
325
    /**
326
     * @var MatcherAPIInterface
327
     */
328
    protected $matcherAPI;
329
330
    /**
331
     * This class implements a singleton, so the only constructor is protected.
332
     * @param MetadataSourceInterface $metadataSource
333
     * @param $countryCallingCodeToRegionCodeMap
334
     */
335 668
    protected function __construct(MetadataSourceInterface $metadataSource, $countryCallingCodeToRegionCodeMap)
336
    {
337 668
        $this->metadataSource = $metadataSource;
338 668
        $this->countryCallingCodeToRegionCodeMap = $countryCallingCodeToRegionCodeMap;
339 668
        $this->init();
340 668
        $this->matcherAPI = RegexBasedMatcher::create();
341 668
        static::initCapturingExtnDigits();
342 668
        static::initExtnPatterns();
343 668
        static::initExtnPattern();
344 668
        static::$PLUS_CHARS_PATTERN = '[' . static::PLUS_CHARS . ']+';
345 668
        static::$SEPARATOR_PATTERN = '[' . static::VALID_PUNCTUATION . ']+';
346 668
        static::$CAPTURING_DIGIT_PATTERN = '(' . static::DIGITS . ')';
347 668
        static::initValidStartCharPattern();
348 668
        static::initAlphaPhoneMappings();
349 668
        static::initDiallableCharMappings();
350
351 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS = array();
352
        // Put (lower letter -> upper letter) and (upper letter -> upper letter) mappings.
353 668
        foreach (static::$ALPHA_MAPPINGS as $c => $value) {
354 668
            static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS[strtolower($c)] = $c;
355 668
            static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS[$c] = $c;
356 668
        }
357 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS += static::$asciiDigitMappings;
358 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS['-'] = '-';
359 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xEF\xBC\x8D"] = '-';
360 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x90"] = '-';
361 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x91"] = '-';
362 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x92"] = '-';
363 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x93"] = '-';
364 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x94"] = '-';
365 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x80\x95"] = '-';
366 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x88\x92"] = '-';
367 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS['/'] = '/';
368 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xEF\xBC\x8F"] = '/';
369 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS[' '] = ' ';
370 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE3\x80\x80"] = ' ';
371 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xE2\x81\xA0"] = ' ';
372 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS['.'] = '.';
373 668
        static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS["\xEF\xBC\x8E"] = '.';
374
375
376 668
        static::initValidPhoneNumberPatterns();
377
378 668
        static::$UNWANTED_END_CHAR_PATTERN = '[^' . static::DIGITS . static::VALID_ALPHA . '#]+$';
379
380 668
        static::initMobileTokenMappings();
381
382 668
        static::$GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES = array();
383 668
        static::$GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES[] = 86; // China
384
385 668
        static::$GEO_MOBILE_COUNTRIES = array();
386 668
        static::$GEO_MOBILE_COUNTRIES[] = 52; // Mexico
387 668
        static::$GEO_MOBILE_COUNTRIES[] = 54; // Argentina
388 668
        static::$GEO_MOBILE_COUNTRIES[] = 55; // Brazil
389 668
        static::$GEO_MOBILE_COUNTRIES[] = 62; // Indonesia: some prefixes only (fixed CMDA wireless)
390
391 668
        static::$GEO_MOBILE_COUNTRIES = array_merge(static::$GEO_MOBILE_COUNTRIES, static::$GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES);
392 668
    }
393
394
    /**
395
     * Gets a {@link PhoneNumberUtil} instance to carry out international phone number formatting,
396
     * parsing, or validation. The instance is loaded with phone number metadata for a number of most
397
     * commonly used regions.
398
     *
399
     * <p>The {@link PhoneNumberUtil} is implemented as a singleton. Therefore, calling getInstance
400
     * multiple times will only result in one instance being created.
401
     *
402
     * @param string $baseFileLocation
403
     * @param array|null $countryCallingCodeToRegionCodeMap
404
     * @param MetadataLoaderInterface|null $metadataLoader
405
     * @param MetadataSourceInterface|null $metadataSource
406
     * @return PhoneNumberUtil instance
407
     */
408 6312
    public static function getInstance($baseFileLocation = self::META_DATA_FILE_PREFIX, array $countryCallingCodeToRegionCodeMap = null, MetadataLoaderInterface $metadataLoader = null, MetadataSourceInterface $metadataSource = null)
409
    {
410 6312
        if (static::$instance === null) {
411 668
            if ($countryCallingCodeToRegionCodeMap === null) {
412 270
                $countryCallingCodeToRegionCodeMap = CountryCodeToRegionCodeMap::$countryCodeToRegionCodeMap;
413 270
            }
414
415 668
            if ($metadataLoader === null) {
416 668
                $metadataLoader = new DefaultMetadataLoader();
417 668
            }
418
419 668
            if ($metadataSource === null) {
420 668
                $metadataSource = new MultiFileMetadataSourceImpl($metadataLoader, __DIR__ . '/data/' . $baseFileLocation);
421 668
            }
422
423 668
            static::$instance = new static($metadataSource, $countryCallingCodeToRegionCodeMap);
424 668
        }
425 6312
        return static::$instance;
426
    }
427
428 668
    protected function init()
429
    {
430 668
        $supportedRegions = array(array());
431
432 668
        foreach ($this->countryCallingCodeToRegionCodeMap as $countryCode => $regionCodes) {
433
            // We can assume that if the country calling code maps to the non-geo entity region code then
434
            // that's the only region code it maps to.
435 668
            if (count($regionCodes) === 1 && static::REGION_CODE_FOR_NON_GEO_ENTITY === $regionCodes[0]) {
436
                // This is the subset of all country codes that map to the non-geo entity region code.
437 668
                $this->countryCodesForNonGeographicalRegion[] = $countryCode;
438 668
            } else {
439
                // The supported regions set does not include the "001" non-geo entity region code.
440 668
                $supportedRegions[] = $regionCodes;
441
            }
442 668
        }
443
444 668
        $this->supportedRegions = call_user_func_array('array_merge', $supportedRegions);
445
446
447
        // If the non-geo entity still got added to the set of supported regions it must be because
448
        // there are entries that list the non-geo entity alongside normal regions (which is wrong).
449
        // If we discover this, remove the non-geo entity from the set of supported regions and log.
450 668
        $idx_region_code_non_geo_entity = array_search(static::REGION_CODE_FOR_NON_GEO_ENTITY, $this->supportedRegions);
451 668
        if ($idx_region_code_non_geo_entity !== false) {
452
            unset($this->supportedRegions[$idx_region_code_non_geo_entity]);
453
        }
454 668
        $this->nanpaRegions = $this->countryCallingCodeToRegionCodeMap[static::NANPA_COUNTRY_CODE];
455 668
    }
456
457
    /**
458
     * @internal
459
     */
460 670
    public static function initCapturingExtnDigits()
461
    {
462 670
        static::$CAPTURING_EXTN_DIGITS = '(' . static::DIGITS . '{1,7})';
463 670
    }
464
465
    /**
466
     * @internal
467
     */
468 670
    public static function initExtnPatterns()
469
    {
470
        // One-character symbols that can be used to indicate an extension.
471 670
        $singleExtnSymbolsForMatching = "x\xEF\xBD\x98#\xEF\xBC\x83~\xEF\xBD\x9E";
472
        // For parsing, we are slightly more lenient in our interpretation than for matching. Here we
473
        // allow "comma" and "semicolon" as possible extension indicators. When matching, these are
474
        // hardly ever used to indicate this.
475 670
        $singleExtnSymbolsForParsing = ',;' . $singleExtnSymbolsForMatching;
476
477 670
        static::$EXTN_PATTERNS_FOR_PARSING = static::createExtnPattern($singleExtnSymbolsForParsing);
478 670
        static::$EXTN_PATTERNS_FOR_MATCHING = static::createExtnPattern($singleExtnSymbolsForMatching);
479 670
    }
480
481
    /**
482
     * Helper initialiser method to create the regular-expression pattern to match extensions,
483
     * allowing the one-char extension symbols provided by {@code singleExtnSymbols}.
484
     * @param string $singleExtnSymbols
485
     * @return string
486
     */
487 670
    protected static function createExtnPattern($singleExtnSymbols)
488
    {
489
        // There are three regular expressions here. The first covers RFC 3966 format, where the
490
        // extension is added using ";ext=". The second more generic one starts with optional white
491
        // space and ends with an optional full stop (.), followed by zero or more spaces/tabs/commas
492
        // and then the numbers themselves. The other one covers the special case of American numbers
493
        // where the extension is written with a hash at the end, such as "- 503#"
494
        // Note that the only capturing groups should be around the digits that you want to capture as
495
        // part of the extension, or else parsing will fail!
496
        // Canonical-equivalence doesn't seem to be an option with Android java, so we allow two options
497
        // for representing the accented o - the character itself, and one in the unicode decomposed
498
        // form with the combining acute accent.
499 670
        return (static::RFC3966_EXTN_PREFIX . static::$CAPTURING_EXTN_DIGITS . '|' . "[ \xC2\xA0\\t,]*" .
500 670
            "(?:e?xt(?:ensi(?:o\xCC\x81?|\xC3\xB3))?n?|(?:\xEF\xBD\x85)?\xEF\xBD\x98\xEF\xBD\x94(?:\xEF\xBD\x8E)?|" .
501 670
            'доб|' . '[' . $singleExtnSymbols . "]|int|\xEF\xBD\x89\xEF\xBD\x8E\xEF\xBD\x94|anexo)" .
502 670
            "[:\\.\xEF\xBC\x8E]?[ \xC2\xA0\\t,-]*" . static::$CAPTURING_EXTN_DIGITS . "\\#?|" .
503 670
            '[- ]+(' . static::DIGITS . "{1,5})\\#");
504
    }
505
506 668
    protected static function initExtnPattern()
507
    {
508 668
        static::$EXTN_PATTERN = '/(?:' . static::$EXTN_PATTERNS_FOR_PARSING . ')$/' . static::REGEX_FLAGS;
509 668
    }
510
511 670
    protected static function initValidPhoneNumberPatterns()
512
    {
513 670
        static::initCapturingExtnDigits();
514 670
        static::initExtnPatterns();
515 670
        static::$MIN_LENGTH_PHONE_NUMBER_PATTERN = '[' . static::DIGITS . ']{' . static::MIN_LENGTH_FOR_NSN . '}';
516 670
        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 . ']*';
517 670
        static::$VALID_PHONE_NUMBER_PATTERN = '%^' . static::$MIN_LENGTH_PHONE_NUMBER_PATTERN . '$|^' . static::$VALID_PHONE_NUMBER . '(?:' . static::$EXTN_PATTERNS_FOR_PARSING . ')?$%' . static::REGEX_FLAGS;
518 670
    }
519
520 670
    protected static function initAlphaPhoneMappings()
521
    {
522 670
        static::$ALPHA_PHONE_MAPPINGS = static::$ALPHA_MAPPINGS + static::$asciiDigitMappings;
523 670
    }
524
525 669
    protected static function initValidStartCharPattern()
526
    {
527 669
        static::$VALID_START_CHAR_PATTERN = '[' . static::PLUS_CHARS . static::DIGITS . ']';
528 669
    }
529
530 669
    protected static function initMobileTokenMappings()
531
    {
532 669
        static::$MOBILE_TOKEN_MAPPINGS = array();
533 669
        static::$MOBILE_TOKEN_MAPPINGS['54'] = '9';
534 669
    }
535
536 669
    protected static function initDiallableCharMappings()
537
    {
538 669
        static::$DIALLABLE_CHAR_MAPPINGS = static::$asciiDigitMappings;
539 669
        static::$DIALLABLE_CHAR_MAPPINGS[static::PLUS_SIGN] = static::PLUS_SIGN;
540 669
        static::$DIALLABLE_CHAR_MAPPINGS['*'] = '*';
541 669
        static::$DIALLABLE_CHAR_MAPPINGS['#'] = '#';
542 669
    }
543
544
    /**
545
     * Used for testing purposes only to reset the PhoneNumberUtil singleton to null.
546
     */
547 674
    public static function resetInstance()
548
    {
549 674
        static::$instance = null;
550 674
    }
551
552
    /**
553
     * Converts all alpha characters in a number to their respective digits on a keypad, but retains
554
     * existing formatting.
555
     * @param string $number
556
     * @return string
557
     */
558 2
    public static function convertAlphaCharactersInNumber($number)
559
    {
560 2
        if (static::$ALPHA_PHONE_MAPPINGS === null) {
0 ignored issues
show
introduced by
The condition static::ALPHA_PHONE_MAPPINGS === null is always false.
Loading history...
561 1
            static::initAlphaPhoneMappings();
562 1
        }
563
564 2
        return static::normalizeHelper($number, static::$ALPHA_PHONE_MAPPINGS, false);
565
    }
566
567
    /**
568
     * Normalizes a string of characters representing a phone number by replacing all characters found
569
     * in the accompanying map with the values therein, and stripping all other characters if
570
     * removeNonMatches is true.
571
     *
572
     * @param string $number a string of characters representing a phone number
573
     * @param array $normalizationReplacements a mapping of characters to what they should be replaced by in
574
     * the normalized version of the phone number
575
     * @param bool $removeNonMatches indicates whether characters that are not able to be replaced
576
     * should be stripped from the number. If this is false, they will be left unchanged in the number.
577
     * @return string the normalized string version of the phone number
578
     */
579 40
    protected static function normalizeHelper($number, array $normalizationReplacements, $removeNonMatches)
580
    {
581 40
        $normalizedNumber = '';
582 40
        $strLength = mb_strlen($number, 'UTF-8');
583 40
        for ($i = 0; $i < $strLength; $i++) {
584 40
            $character = mb_substr($number, $i, 1, 'UTF-8');
585 40
            if (isset($normalizationReplacements[mb_strtoupper($character, 'UTF-8')])) {
586 40
                $normalizedNumber .= $normalizationReplacements[mb_strtoupper($character, 'UTF-8')];
587 40
            } elseif (!$removeNonMatches) {
588 2
                $normalizedNumber .= $character;
589 2
            }
590
            // If neither of the above are true, we remove this character.
591 40
        }
592 40
        return $normalizedNumber;
593
    }
594
595
    /**
596
     * Helper function to check if the national prefix formatting rule has the first group only, i.e.,
597
     * does not start with the national prefix.
598
     * @param string $nationalPrefixFormattingRule
599
     * @return bool
600
     */
601 61
    public static function formattingRuleHasFirstGroupOnly($nationalPrefixFormattingRule)
602
    {
603 61
        $firstGroupOnlyPrefixPatternMatcher = new Matcher(static::FIRST_GROUP_ONLY_PREFIX_PATTERN,
604 61
            $nationalPrefixFormattingRule);
605
606 61
        return mb_strlen($nationalPrefixFormattingRule) === 0
607 61
            || $firstGroupOnlyPrefixPatternMatcher->matches();
608
    }
609
610
    /**
611
     * Returns all regions the library has metadata for.
612
     *
613
     * @return array An unordered array of the two-letter region codes for every geographical region the
614
     *  library supports
615
     */
616 246
    public function getSupportedRegions()
617
    {
618 246
        return $this->supportedRegions;
619
    }
620
621
    /**
622
     * Returns all global network calling codes the library has metadata for.
623
     *
624
     * @return array An unordered array of the country calling codes for every non-geographical entity
625
     *  the library supports
626
     */
627 2
    public function getSupportedGlobalNetworkCallingCodes()
628
    {
629 2
        return $this->countryCodesForNonGeographicalRegion;
630
    }
631
632
    /**
633
     * Returns all country calling codes the library has metadata for, covering both non-geographical
634
     * entities (global network calling codes) and those used for geographical entities. The could be
635
     * used to populate a drop-down box of country calling codes for a phone-number widget, for
636
     * instance.
637
     *
638
     * @return array An unordered array of the country calling codes for every geographical and
639
     *      non-geographical entity the library supports
640
     */
641 1
    public function getSupportedCallingCodes()
642
    {
643 1
        return array_keys($this->countryCallingCodeToRegionCodeMap);
644
    }
645
646
    /**
647
     * Returns true if there is any possible number data set for a particular PhoneNumberDesc.
648
     *
649
     * @param PhoneNumberDesc $desc
650
     * @return bool
651
     */
652 5
    protected static function descHasPossibleNumberData(PhoneNumberDesc $desc)
653
    {
654
        // If this is empty, it means numbers of this type inherit from the "general desc" -> the value
655
        // '-1' means that no numbers exist for this type.
656 5
        $possibleLength = $desc->getPossibleLength();
657 5
        return count($possibleLength) != 1 || $possibleLength[0] != -1;
658
    }
659
660
    /**
661
     * Returns true if there is any data set for a particular PhoneNumberDesc.
662
     *
663
     * @param PhoneNumberDesc $desc
664
     * @return bool
665
     */
666 2
    protected static function descHasData(PhoneNumberDesc $desc)
667
    {
668
        // Checking most properties since we don't know what's present, since a custom build may have
669
        // stripped just one of them (e.g. liteBuild strips exampleNumber). We don't bother checking the
670
        // possibleLengthsLocalOnly, since if this is the only thing that's present we don't really
671
        // support the type at all: no type-specific methods will work with only this data.
672 2
        return $desc->hasExampleNumber()
673 2
            || static::descHasPossibleNumberData($desc)
674 2
            || $desc->hasNationalNumberPattern();
675
    }
676
677
    /**
678
     * Returns the types we have metadata for based on the PhoneMetadata object passed in
679
     *
680
     * @param PhoneMetadata $metadata
681
     * @return array
682
     */
683 2
    private function getSupportedTypesForMetadata(PhoneMetadata $metadata)
684
    {
685 2
        $types = array();
686 2
        foreach (array_keys(PhoneNumberType::values()) as $type) {
687 2
            if ($type === PhoneNumberType::FIXED_LINE_OR_MOBILE || $type === PhoneNumberType::UNKNOWN) {
688
                // Never return FIXED_LINE_OR_MOBILE (it is a convenience type, and represents that a
689
                // particular number type can't be determined) or UNKNOWN (the non-type).
690 2
                continue;
691
            }
692
693 2
            if (self::descHasData($this->getNumberDescByType($metadata, $type))) {
694 2
                $types[] = $type;
695 2
            }
696 2
        }
697
698 2
        return $types;
699
    }
700
701
    /**
702
     * Returns the types for a given region which the library has metadata for. Will not include
703
     * FIXED_LINE_OR_MOBILE (if the numbers in this region could be classified as FIXED_LINE_OR_MOBILE,
704
     * both FIXED_LINE and MOBILE would be present) and UNKNOWN.
705
     *
706
     * No types will be returned for invalid or unknown region codes.
707
     *
708
     * @param string $regionCode
709
     * @return array
710
     */
711 1
    public function getSupportedTypesForRegion($regionCode)
712
    {
713 1
        if (!$this->isValidRegionCode($regionCode)) {
714 1
            return array();
715
        }
716 1
        $metadata = $this->getMetadataForRegion($regionCode);
717 1
        return $this->getSupportedTypesForMetadata($metadata);
718
    }
719
720
    /**
721
     * Returns the types for a country-code belonging to a non-geographical entity which the library
722
     * has metadata for. Will not include FIXED_LINE_OR_MOBILE (if numbers for this non-geographical
723
     * entity could be classified as FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would be
724
     * present) and UNKNOWN.
725
     *
726
     * @param int $countryCallingCode
727
     * @return array
728
     */
729 1
    public function getSupportedTypesForNonGeoEntity($countryCallingCode)
730
    {
731 1
        $metadata = $this->getMetadataForNonGeographicalRegion($countryCallingCode);
732 1
        if ($metadata === null) {
733 1
            return array();
734
        }
735
736 1
        return $this->getSupportedTypesForMetadata($metadata);
737
    }
738
739
    /**
740
     * Gets the length of the geographical area code from the {@code nationalNumber} field of the
741
     * PhoneNumber object passed in, so that clients could use it to split a national significant
742
     * number into geographical area code and subscriber number. It works in such a way that the
743
     * resultant subscriber number should be diallable, at least on some devices. An example of how
744
     * this could be used:
745
     *
746
     * <code>
747
     * $phoneUtil = PhoneNumberUtil::getInstance();
748
     * $number = $phoneUtil->parse("16502530000", "US");
749
     * $nationalSignificantNumber = $phoneUtil->getNationalSignificantNumber($number);
750
     *
751
     * $areaCodeLength = $phoneUtil->getLengthOfGeographicalAreaCode($number);
752
     * if ($areaCodeLength > 0)
753
     * {
754
     *     $areaCode = substr($nationalSignificantNumber, 0,$areaCodeLength);
755
     *     $subscriberNumber = substr($nationalSignificantNumber, $areaCodeLength);
756
     * } else {
757
     *     $areaCode = "";
758
     *     $subscriberNumber = $nationalSignificantNumber;
759
     * }
760
     * </code>
761
     *
762
     * N.B.: area code is a very ambiguous concept, so the I18N team generally recommends against
763
     * using it for most purposes, but recommends using the more general {@code nationalNumber}
764
     * instead. Read the following carefully before deciding to use this method:
765
     * <ul>
766
     *  <li> geographical area codes change over time, and this method honors those changes;
767
     *    therefore, it doesn't guarantee the stability of the result it produces.
768
     *  <li> subscriber numbers may not be diallable from all devices (notably mobile devices, which
769
     *    typically requires the full national_number to be dialled in most regions).
770
     *  <li> most non-geographical numbers have no area codes, including numbers from non-geographical
771
     *    entities
772
     *  <li> some geographical numbers have no area codes.
773
     * </ul>
774
     * @param PhoneNumber $number PhoneNumber object for which clients want to know the length of the area code.
775
     * @return int the length of area code of the PhoneNumber object passed in.
776
     */
777 1
    public function getLengthOfGeographicalAreaCode(PhoneNumber $number)
778
    {
779 1
        $metadata = $this->getMetadataForRegion($this->getRegionCodeForNumber($number));
780 1
        if ($metadata === null) {
781 1
            return 0;
782
        }
783
        // If a country doesn't use a national prefix, and this number doesn't have an Italian leading
784
        // zero, we assume it is a closed dialling plan with no area codes.
785 1
        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...
786 1
            return 0;
787
        }
788
789 1
        $type = $this->getNumberType($number);
790 1
        $countryCallingCode = $number->getCountryCode();
791
792
        if ($type === PhoneNumberType::MOBILE
793
            // Note this is a rough heuristic; it doesn't cover Indonesia well, for example, where area
794
            // codes are present for some mobile phones but not for others. We have no better way of
795
            // representing this in the metadata at this point.
796 1
            && in_array($countryCallingCode, self::$GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES)
797 1
        ) {
798 1
            return 0;
799
        }
800
801 1
        if (!$this->isNumberGeographical($type, $countryCallingCode)) {
802 1
            return 0;
803
        }
804
805 1
        return $this->getLengthOfNationalDestinationCode($number);
806
    }
807
808
    /**
809
     * Returns the metadata for the given region code or {@code null} if the region code is invalid
810
     * or unknown.
811
     * @param string $regionCode
812
     * @return PhoneMetadata
813
     */
814 5220
    public function getMetadataForRegion($regionCode)
815
    {
816 5220
        if (!$this->isValidRegionCode($regionCode)) {
817 348
            return null;
818
        }
819
820 5207
        return $this->metadataSource->getMetadataForRegion($regionCode);
821
    }
822
823
    /**
824
     * Helper function to check region code is not unknown or null.
825
     * @param string $regionCode
826
     * @return bool
827
     */
828 5221
    protected function isValidRegionCode($regionCode)
829
    {
830 5221
        return $regionCode !== null && in_array($regionCode, $this->supportedRegions);
831
    }
832
833
    /**
834
     * Returns the region where a phone number is from. This could be used for geocoding at the region
835
     * level. Only guarantees correct results for valid, full numbers (not short-codes, or invalid
836
     * numbers).
837
     *
838
     * @param PhoneNumber $number the phone number whose origin we want to know
839
     * @return null|string  the region where the phone number is from, or null if no region matches this calling
840
     * code
841
     */
842 2283
    public function getRegionCodeForNumber(PhoneNumber $number)
843
    {
844 2283
        $countryCode = $number->getCountryCode();
845 2283
        if (!isset($this->countryCallingCodeToRegionCodeMap[$countryCode])) {
846 4
            return null;
847
        }
848 2282
        $regions = $this->countryCallingCodeToRegionCodeMap[$countryCode];
849 2282
        if (count($regions) == 1) {
850 1714
            return $regions[0];
851
        }
852
853 592
        return $this->getRegionCodeForNumberFromRegionList($number, $regions);
854
    }
855
856
    /**
857
     * @param PhoneNumber $number
858
     * @param array $regionCodes
859
     * @return null|string
860
     */
861 592
    protected function getRegionCodeForNumberFromRegionList(PhoneNumber $number, array $regionCodes)
862
    {
863 592
        $nationalNumber = $this->getNationalSignificantNumber($number);
864 592
        foreach ($regionCodes as $regionCode) {
865
            // If leadingDigits is present, use this. Otherwise, do full validation.
866
            // Metadata cannot be null because the region codes come from the country calling code map.
867 592
            $metadata = $this->getMetadataForRegion($regionCode);
868 592
            if ($metadata->hasLeadingDigits()) {
869 285
                $nbMatches = preg_match(
870 285
                    '/' . $metadata->getLeadingDigits() . '/',
871 285
                    $nationalNumber,
872 285
                    $matches,
873
                    PREG_OFFSET_CAPTURE
874 285
                );
875 285
                if ($nbMatches > 0 && $matches[0][1] === 0) {
876 263
                    return $regionCode;
877
                }
878 522
            } elseif ($this->getNumberTypeHelper($nationalNumber, $metadata) != PhoneNumberType::UNKNOWN) {
879 276
                return $regionCode;
880
            }
881 298
        }
882 70
        return null;
883
    }
884
885
    /**
886
     * Gets the national significant number of the a phone number. Note a national significant number
887
     * doesn't contain a national prefix or any formatting.
888
     *
889
     * @param PhoneNumber $number the phone number for which the national significant number is needed
890
     * @return string the national significant number of the PhoneNumber object passed in
891
     */
892 2182
    public function getNationalSignificantNumber(PhoneNumber $number)
893
    {
894
        // If leading zero(s) have been set, we prefix this now. Note this is not a national prefix.
895 2182
        $nationalNumber = '';
896 2182
        if ($number->isItalianLeadingZero() && $number->getNumberOfLeadingZeros() > 0) {
897 82
            $zeros = str_repeat('0', $number->getNumberOfLeadingZeros());
898 82
            $nationalNumber .= $zeros;
899 82
        }
900 2182
        $nationalNumber .= $number->getNationalNumber();
901 2182
        return $nationalNumber;
902
    }
903
904
    /**
905
     * @param string $nationalNumber
906
     * @param PhoneMetadata $metadata
907
     * @return int PhoneNumberType constant
908
     */
909 2084
    protected function getNumberTypeHelper($nationalNumber, PhoneMetadata $metadata)
910
    {
911 2084
        if (!$this->isNumberMatchingDesc($nationalNumber, $metadata->getGeneralDesc())) {
912 320
            return PhoneNumberType::UNKNOWN;
913
        }
914 1823
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPremiumRate())) {
915 163
            return PhoneNumberType::PREMIUM_RATE;
916
        }
917 1661
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getTollFree())) {
918 194
            return PhoneNumberType::TOLL_FREE;
919
        }
920
921
922 1479
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getSharedCost())) {
923 56
            return PhoneNumberType::SHARED_COST;
924
        }
925 1423
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getVoip())) {
926 90
            return PhoneNumberType::VOIP;
927
        }
928 1337
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPersonalNumber())) {
929 61
            return PhoneNumberType::PERSONAL_NUMBER;
930
        }
931 1276
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPager())) {
932 23
            return PhoneNumberType::PAGER;
933
        }
934 1255
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getUan())) {
935 63
            return PhoneNumberType::UAN;
936
        }
937 1195
        if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getVoicemail())) {
938 15
            return PhoneNumberType::VOICEMAIL;
939
        }
940 1181
        $isFixedLine = $this->isNumberMatchingDesc($nationalNumber, $metadata->getFixedLine());
941 1181
        if ($isFixedLine) {
942 886
            if ($metadata->getSameMobileAndFixedLinePattern()) {
943
                return PhoneNumberType::FIXED_LINE_OR_MOBILE;
944
            }
945
946 886
            if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getMobile())) {
947 112
                return PhoneNumberType::FIXED_LINE_OR_MOBILE;
948
            }
949 783
            return PhoneNumberType::FIXED_LINE;
950
        }
951
        // Otherwise, test to see if the number is mobile. Only do this if certain that the patterns for
952
        // mobile and fixed line aren't the same.
953 423
        if (!$metadata->getSameMobileAndFixedLinePattern() &&
954 423
            $this->isNumberMatchingDesc($nationalNumber, $metadata->getMobile())
955 423
        ) {
956 260
            return PhoneNumberType::MOBILE;
957
        }
958 188
        return PhoneNumberType::UNKNOWN;
959
    }
960
961
    /**
962
     * @param string $nationalNumber
963
     * @param PhoneNumberDesc $numberDesc
964
     * @return bool
965
     */
966 2084
    public function isNumberMatchingDesc($nationalNumber, PhoneNumberDesc $numberDesc)
967
    {
968
        // Check if any possible number lengths are present; if so, we use them to avoid checking the
969
        // validation pattern if they don't match. If they are absent, this means they match the general
970
        // description, which we have already checked before checking a specific number type.
971 2084
        $actualLength = mb_strlen($nationalNumber);
972 2084
        $possibleLengths = $numberDesc->getPossibleLength();
973 2084
        if (count($possibleLengths) > 0 && !in_array($actualLength, $possibleLengths)) {
974 1685
            return false;
975
        }
976
977 1860
        return $this->matcherAPI->matchNationalNumber($nationalNumber, $numberDesc, false);
978
    }
979
980
    /**
981
     * isNumberGeographical(PhoneNumber)
982
     *
983
     * Tests whether a phone number has a geographical association. It checks if the number is
984
     * associated with a certain region in the country to which it belongs. Note that this doesn't
985
     * verify if the number is actually in use.
986
     *
987
     * isNumberGeographical(PhoneNumberType, $countryCallingCode)
988
     *
989
     * Tests whether a phone number has a geographical association, as represented by its type and the
990
     * country it belongs to.
991
     *
992
     * This version exists since calculating the phone number type is expensive; if we have already
993
     * done this, we don't want to do it again.
994
     *
995
     * @param PhoneNumber|int $phoneNumberObjOrType A PhoneNumber object, or a PhoneNumberType integer
996
     * @param int|null $countryCallingCode Used when passing a PhoneNumberType
997
     * @return bool
998
     */
999 21
    public function isNumberGeographical($phoneNumberObjOrType, $countryCallingCode = null)
1000
    {
1001 21
        if ($phoneNumberObjOrType instanceof PhoneNumber) {
1002 1
            return $this->isNumberGeographical($this->getNumberType($phoneNumberObjOrType), $phoneNumberObjOrType->getCountryCode());
1003
        }
1004
1005
        return $phoneNumberObjOrType == PhoneNumberType::FIXED_LINE
1006 21
        || $phoneNumberObjOrType == PhoneNumberType::FIXED_LINE_OR_MOBILE
1007 17
        || (in_array($countryCallingCode, static::$GEO_MOBILE_COUNTRIES)
1008 21
            && $phoneNumberObjOrType == PhoneNumberType::MOBILE);
1009
    }
1010
1011
    /**
1012
     * Gets the type of a valid phone number.
1013
     * @param PhoneNumber $number the number the phone number that we want to know the type
1014
     * @return int PhoneNumberType the type of the phone number, or UNKNOWN if it is invalid
1015
     */
1016 1392
    public function getNumberType(PhoneNumber $number)
1017
    {
1018 1392
        $regionCode = $this->getRegionCodeForNumber($number);
1019 1392
        $metadata = $this->getMetadataForRegionOrCallingCode($number->getCountryCode(), $regionCode);
1020 1392
        if ($metadata === null) {
1021 8
            return PhoneNumberType::UNKNOWN;
1022
        }
1023 1391
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
1024 1391
        return $this->getNumberTypeHelper($nationalSignificantNumber, $metadata);
1025
    }
1026
1027
    /**
1028
     * @param int $countryCallingCode
1029
     * @param string $regionCode
1030
     * @return PhoneMetadata
1031
     */
1032 2135
    protected function getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode)
1033
    {
1034 2135
        return static::REGION_CODE_FOR_NON_GEO_ENTITY === $regionCode ?
1035 2135
            $this->getMetadataForNonGeographicalRegion($countryCallingCode) : $this->getMetadataForRegion($regionCode);
1036
    }
1037
1038
    /**
1039
     * @param int $countryCallingCode
1040
     * @return PhoneMetadata
1041
     */
1042 34
    public function getMetadataForNonGeographicalRegion($countryCallingCode)
1043
    {
1044 34
        if (!isset($this->countryCallingCodeToRegionCodeMap[$countryCallingCode])) {
1045 2
            return null;
1046
        }
1047 34
        return $this->metadataSource->getMetadataForNonGeographicalRegion($countryCallingCode);
1048
    }
1049
1050
    /**
1051
     * Gets the length of the national destination code (NDC) from the PhoneNumber object passed in,
1052
     * so that clients could use it to split a national significant number into NDC and subscriber
1053
     * number. The NDC of a phone number is normally the first group of digit(s) right after the
1054
     * country calling code when the number is formatted in the international format, if there is a
1055
     * subscriber number part that follows.
1056
     *
1057
     * follows.
1058
     *
1059
     * N.B.: similar to an area code, not all numbers have an NDC!
1060
     *
1061
     * An example of how this could be used:
1062
     *
1063
     * <code>
1064
     * $phoneUtil = PhoneNumberUtil::getInstance();
1065
     * $number = $phoneUtil->parse("18002530000", "US");
1066
     * $nationalSignificantNumber = $phoneUtil->getNationalSignificantNumber($number);
1067
     *
1068
     * $nationalDestinationCodeLength = $phoneUtil->getLengthOfNationalDestinationCode($number);
1069
     * if ($nationalDestinationCodeLength > 0) {
1070
     *     $nationalDestinationCode = substr($nationalSignificantNumber, 0, $nationalDestinationCodeLength);
1071
     *     $subscriberNumber = substr($nationalSignificantNumber, $nationalDestinationCodeLength);
1072
     * } else {
1073
     *     $nationalDestinationCode = "";
1074
     *     $subscriberNumber = $nationalSignificantNumber;
1075
     * }
1076
     * </code>
1077
     *
1078
     * Refer to the unit tests to see the difference between this function and
1079
     * {@link #getLengthOfGeographicalAreaCode}.
1080
     *
1081
     * @param PhoneNumber $number the PhoneNumber object for which clients want to know the length of the NDC.
1082
     * @return int the length of NDC of the PhoneNumber object passed in, which could be zero
1083
     */
1084 2
    public function getLengthOfNationalDestinationCode(PhoneNumber $number)
1085
    {
1086 2
        if ($number->hasExtension()) {
1087
            // We don't want to alter the proto given to us, but we don't want to include the extension
1088
            // when we format it, so we copy it and clear the extension here.
1089
            $copiedProto = new PhoneNumber();
1090
            $copiedProto->mergeFrom($number);
1091
            $copiedProto->clearExtension();
1092
        } else {
1093 2
            $copiedProto = clone $number;
1094
        }
1095
1096 2
        $nationalSignificantNumber = $this->format($copiedProto, PhoneNumberFormat::INTERNATIONAL);
1097
1098 2
        $numberGroups = preg_split('/' . static::NON_DIGITS_PATTERN . '/', $nationalSignificantNumber);
1099
1100
        // The pattern will start with "+COUNTRY_CODE " so the first group will always be the empty
1101
        // string (before the + symbol) and the second group will be the country calling code. The third
1102
        // group will be area code if it is not the last group.
1103 2
        if (count($numberGroups) <= 3) {
0 ignored issues
show
Bug introduced by
It seems like $numberGroups can also be of type false; however, parameter $var of count() does only seem to accept Countable|array, maybe add an additional type check? ( Ignorable by Annotation )

If this is a false-positive, you can also ignore this issue in your code via the ignore-type  annotation

1103
        if (count(/** @scrutinizer ignore-type */ $numberGroups) <= 3) {
Loading history...
1104 1
            return 0;
1105
        }
1106
1107 2
        if ($this->getNumberType($number) == PhoneNumberType::MOBILE) {
1108
            // For example Argentinian mobile numbers, when formatted in the international format, are in
1109
            // the form of +54 9 NDC XXXX.... As a result, we take the length of the third group (NDC) and
1110
            // add the length of the second group (which is the mobile token), which also forms part of
1111
            // the national significant number. This assumes that the mobile token is always formatted
1112
            // separately from the rest of the phone number.
1113
1114 2
            $mobileToken = static::getCountryMobileToken($number->getCountryCode());
1115 2
            if ($mobileToken !== '') {
1116 2
                return mb_strlen($numberGroups[2]) + mb_strlen($numberGroups[3]);
1117
            }
1118 1
        }
1119 2
        return mb_strlen($numberGroups[2]);
1120
    }
1121
1122
    /**
1123
     * Formats a phone number in the specified format using default rules. Note that this does not
1124
     * promise to produce a phone number that the user can dial from where they are - although we do
1125
     * format in either 'national' or 'international' format depending on what the client asks for, we
1126
     * do not currently support a more abbreviated format, such as for users in the same "area" who
1127
     * could potentially dial the number without area code. Note that if the phone number has a
1128
     * country calling code of 0 or an otherwise invalid country calling code, we cannot work out
1129
     * which formatting rules to apply so we return the national significant number with no formatting
1130
     * applied.
1131
     *
1132
     * @param PhoneNumber $number the phone number to be formatted
1133
     * @param int $numberFormat the PhoneNumberFormat the phone number should be formatted into
1134
     * @return string the formatted phone number
1135
     */
1136 344
    public function format(PhoneNumber $number, $numberFormat)
1137
    {
1138 344
        if ($number->getNationalNumber() == 0 && $number->hasRawInput()) {
0 ignored issues
show
Bug Best Practice introduced by
It seems like you are loosely comparing $number->getNationalNumber() of type null|string 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...
1139
            // Unparseable numbers that kept their raw input just use that.
1140
            // This is the only case where a number can be formatted as E164 without a
1141
            // leading '+' symbol (but the original number wasn't parseable anyway).
1142
            // TODO: Consider removing the 'if' above so that unparseable
1143
            // strings without raw input format to the empty string instead of "+00"
1144 1
            $rawInput = $number->getRawInput();
1145 1
            if (mb_strlen($rawInput) > 0) {
1146 1
                return $rawInput;
1147
            }
1148
        }
1149
1150 344
        $formattedNumber = '';
1151 344
        $countryCallingCode = $number->getCountryCode();
1152 344
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
1153
1154 344
        if ($numberFormat == PhoneNumberFormat::E164) {
1155
            // Early exit for E164 case (even if the country calling code is invalid) since no formatting
1156
            // of the national number needs to be applied. Extensions are not formatted.
1157 266
            $formattedNumber .= $nationalSignificantNumber;
1158 266
            $this->prefixNumberWithCountryCallingCode($countryCallingCode, PhoneNumberFormat::E164, $formattedNumber);
1159 266
            return $formattedNumber;
1160
        }
1161
1162 95
        if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
1163 1
            $formattedNumber .= $nationalSignificantNumber;
1164 1
            return $formattedNumber;
1165
        }
1166
1167
        // Note getRegionCodeForCountryCode() is used because formatting information for regions which
1168
        // share a country calling code is contained by only one region for performance reasons. For
1169
        // example, for NANPA regions it will be contained in the metadata for US.
1170 95
        $regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
1171
        // Metadata cannot be null because the country calling code is valid (which means that the
1172
        // region code cannot be ZZ and must be one of our supported region codes).
1173 95
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode);
1174 95
        $formattedNumber .= $this->formatNsn($nationalSignificantNumber, $metadata, $numberFormat);
1175 95
        $this->maybeAppendFormattedExtension($number, $metadata, $numberFormat, $formattedNumber);
1176 95
        $this->prefixNumberWithCountryCallingCode($countryCallingCode, $numberFormat, $formattedNumber);
1177 95
        return $formattedNumber;
1178
    }
1179
1180
    /**
1181
     * A helper function that is used by format and formatByPattern.
1182
     * @param int $countryCallingCode
1183
     * @param int $numberFormat PhoneNumberFormat
1184
     * @param string $formattedNumber
1185
     */
1186 345
    protected function prefixNumberWithCountryCallingCode($countryCallingCode, $numberFormat, &$formattedNumber)
1187
    {
1188
        switch ($numberFormat) {
1189 345
            case PhoneNumberFormat::E164:
1190 266
                $formattedNumber = static::PLUS_SIGN . $countryCallingCode . $formattedNumber;
1191 266
                return;
1192 96
            case PhoneNumberFormat::INTERNATIONAL:
1193 20
                $formattedNumber = static::PLUS_SIGN . $countryCallingCode . ' ' . $formattedNumber;
1194 20
                return;
1195 93
            case PhoneNumberFormat::RFC3966:
1196 59
                $formattedNumber = static::RFC3966_PREFIX . static::PLUS_SIGN . $countryCallingCode . '-' . $formattedNumber;
1197 59
                return;
1198 39
            case PhoneNumberFormat::NATIONAL:
1199 39
            default:
1200 39
                return;
1201
        }
1202
    }
1203
1204
    /**
1205
     * Helper function to check the country calling code is valid.
1206
     * @param int $countryCallingCode
1207
     * @return bool
1208
     */
1209 165
    protected function hasValidCountryCallingCode($countryCallingCode)
1210
    {
1211 165
        return isset($this->countryCallingCodeToRegionCodeMap[$countryCallingCode]);
1212
    }
1213
1214
    /**
1215
     * Returns the region code that matches the specific country calling code. In the case of no
1216
     * region code being found, ZZ will be returned. In the case of multiple regions, the one
1217
     * designated in the metadata as the "main" region for this calling code will be returned. If the
1218
     * countryCallingCode entered is valid but doesn't match a specific region (such as in the case of
1219
     * non-geographical calling codes like 800) the value "001" will be returned (corresponding to
1220
     * the value for World in the UN M.49 schema).
1221
     *
1222
     * @param int $countryCallingCode
1223
     * @return string
1224
     */
1225 521
    public function getRegionCodeForCountryCode($countryCallingCode)
1226
    {
1227 521
        $regionCodes = isset($this->countryCallingCodeToRegionCodeMap[$countryCallingCode]) ? $this->countryCallingCodeToRegionCodeMap[$countryCallingCode] : null;
1228 521
        return $regionCodes === null ? static::UNKNOWN_REGION : $regionCodes[0];
1229
    }
1230
1231
    /**
1232
     * Note in some regions, the national number can be written in two completely different ways
1233
     * depending on whether it forms part of the NATIONAL format or INTERNATIONAL format. The
1234
     * numberFormat parameter here is used to specify which format to use for those cases. If a
1235
     * carrierCode is specified, this will be inserted into the formatted string to replace $CC.
1236
     * @param string $number
1237
     * @param PhoneMetadata $metadata
1238
     * @param int $numberFormat PhoneNumberFormat
1239
     * @param null|string $carrierCode
1240
     * @return string
1241
     */
1242 96
    protected function formatNsn($number, PhoneMetadata $metadata, $numberFormat, $carrierCode = null)
1243
    {
1244 96
        $intlNumberFormats = $metadata->intlNumberFormats();
1245
        // When the intlNumberFormats exists, we use that to format national number for the
1246
        // INTERNATIONAL format instead of using the numberDesc.numberFormats.
1247 96
        $availableFormats = (count($intlNumberFormats) == 0 || $numberFormat == PhoneNumberFormat::NATIONAL)
1248 96
            ? $metadata->numberFormats()
1249 96
            : $metadata->intlNumberFormats();
1250 96
        $formattingPattern = $this->chooseFormattingPatternForNumber($availableFormats, $number);
1251 96
        return ($formattingPattern === null)
1252 96
            ? $number
1253 96
            : $this->formatNsnUsingPattern($number, $formattingPattern, $numberFormat, $carrierCode);
1254
    }
1255
1256
    /**
1257
     * @param NumberFormat[] $availableFormats
1258
     * @param string $nationalNumber
1259
     * @return NumberFormat|null
1260
     */
1261 129
    public function chooseFormattingPatternForNumber(array $availableFormats, $nationalNumber)
1262
    {
1263 129
        foreach ($availableFormats as $numFormat) {
1264 129
            $leadingDigitsPatternMatcher = null;
1265 129
            $size = $numFormat->leadingDigitsPatternSize();
1266
            // We always use the last leading_digits_pattern, as it is the most detailed.
1267 129
            if ($size > 0) {
1268 98
                $leadingDigitsPatternMatcher = new Matcher(
1269 98
                    $numFormat->getLeadingDigitsPattern($size - 1),
1270
                    $nationalNumber
1271 98
                );
1272 98
            }
1273 129
            if ($size == 0 || $leadingDigitsPatternMatcher->lookingAt()) {
1274 128
                $m = new Matcher($numFormat->getPattern(), $nationalNumber);
1275 128
                if ($m->matches() > 0) {
1276 128
                    return $numFormat;
1277
                }
1278 55
            }
1279 114
        }
1280 9
        return null;
1281
    }
1282
1283
    /**
1284
     * Note that carrierCode is optional - if null or an empty string, no carrier code replacement
1285
     * will take place.
1286
     * @param string $nationalNumber
1287
     * @param NumberFormat $formattingPattern
1288
     * @param int $numberFormat PhoneNumberFormat
1289
     * @param null|string $carrierCode
1290
     * @return string
1291
     */
1292 96
    public function formatNsnUsingPattern(
1293
        $nationalNumber,
1294
        NumberFormat $formattingPattern,
1295
        $numberFormat,
1296
        $carrierCode = null
1297
    ) {
1298 96
        $numberFormatRule = $formattingPattern->getFormat();
1299 96
        $m = new Matcher($formattingPattern->getPattern(), $nationalNumber);
1300 96
        if ($numberFormat === PhoneNumberFormat::NATIONAL &&
1301 96
            $carrierCode !== null && mb_strlen($carrierCode) > 0 &&
1302 2
            mb_strlen($formattingPattern->getDomesticCarrierCodeFormattingRule()) > 0
1303 96
        ) {
1304
            // Replace the $CC in the formatting rule with the desired carrier code.
1305 2
            $carrierCodeFormattingRule = $formattingPattern->getDomesticCarrierCodeFormattingRule();
1306 2
            $carrierCodeFormattingRule = str_replace(static::CC_STRING, $carrierCode, $carrierCodeFormattingRule);
1307
            // Now replace the $FG in the formatting rule with the first group and the carrier code
1308
            // combined in the appropriate way.
1309 2
            $firstGroupMatcher = new Matcher(static::FIRST_GROUP_PATTERN, $numberFormatRule);
1310 2
            $numberFormatRule = $firstGroupMatcher->replaceFirst($carrierCodeFormattingRule);
1311 2
            $formattedNationalNumber = $m->replaceAll($numberFormatRule);
1312 2
        } else {
1313
            // Use the national prefix formatting rule instead.
1314 96
            $nationalPrefixFormattingRule = $formattingPattern->getNationalPrefixFormattingRule();
1315 96
            if ($numberFormat == PhoneNumberFormat::NATIONAL &&
1316 96
                $nationalPrefixFormattingRule !== null &&
1317 22
                mb_strlen($nationalPrefixFormattingRule) > 0
1318 96
            ) {
1319 22
                $firstGroupMatcher = new Matcher(static::FIRST_GROUP_PATTERN, $numberFormatRule);
1320 22
                $formattedNationalNumber = $m->replaceAll(
1321 22
                    $firstGroupMatcher->replaceFirst($nationalPrefixFormattingRule)
1322 22
                );
1323 22
            } else {
1324 89
                $formattedNationalNumber = $m->replaceAll($numberFormatRule);
1325
            }
1326
        }
1327 96
        if ($numberFormat == PhoneNumberFormat::RFC3966) {
1328
            // Strip any leading punctuation.
1329 59
            $matcher = new Matcher(static::$SEPARATOR_PATTERN, $formattedNationalNumber);
1330 59
            if ($matcher->lookingAt()) {
1331 1
                $formattedNationalNumber = $matcher->replaceFirst('');
1332 1
            }
1333
            // Replace the rest with a dash between each number group.
1334 59
            $formattedNationalNumber = $matcher->reset($formattedNationalNumber)->replaceAll('-');
1335 59
        }
1336 96
        return $formattedNationalNumber;
1337
    }
1338
1339
    /**
1340
     * Appends the formatted extension of a phone number to formattedNumber, if the phone number had
1341
     * an extension specified.
1342
     *
1343
     * @param PhoneNumber $number
1344
     * @param PhoneMetadata|null $metadata
1345
     * @param int $numberFormat PhoneNumberFormat
1346
     * @param string $formattedNumber
1347
     */
1348 97
    protected function maybeAppendFormattedExtension(PhoneNumber $number, $metadata, $numberFormat, &$formattedNumber)
1349
    {
1350 97
        if ($number->hasExtension() && mb_strlen($number->getExtension()) > 0) {
1351 13
            if ($numberFormat === PhoneNumberFormat::RFC3966) {
1352 12
                $formattedNumber .= static::RFC3966_EXTN_PREFIX . $number->getExtension();
1353 13
            } elseif (!empty($metadata) && $metadata->hasPreferredExtnPrefix()) {
1354 2
                $formattedNumber .= $metadata->getPreferredExtnPrefix() . $number->getExtension();
1355 2
            } else {
1356 2
                $formattedNumber .= static::DEFAULT_EXTN_PREFIX . $number->getExtension();
1357
            }
1358 13
        }
1359 97
    }
1360
1361
    /**
1362
     * Returns the mobile token for the provided country calling code if it has one, otherwise
1363
     * returns an empty string. A mobile token is a number inserted before the area code when dialing
1364
     * a mobile number from that country from abroad.
1365
     *
1366
     * @param int $countryCallingCode the country calling code for which we want the mobile token
1367
     * @return string the mobile token, as a string, for the given country calling code
1368
     */
1369 16
    public static function getCountryMobileToken($countryCallingCode)
1370
    {
1371 16
        if (count(static::$MOBILE_TOKEN_MAPPINGS) === 0) {
1372 1
            static::initMobileTokenMappings();
1373 1
        }
1374
1375 16
        if (array_key_exists($countryCallingCode, static::$MOBILE_TOKEN_MAPPINGS)) {
1376 5
            return static::$MOBILE_TOKEN_MAPPINGS[$countryCallingCode];
1377
        }
1378 14
        return '';
1379
    }
1380
1381
    /**
1382
     * Checks if the number is a valid vanity (alpha) number such as 800 MICROSOFT. A valid vanity
1383
     * number will start with at least 3 digits and will have three or more alpha characters. This
1384
     * does not do region-specific checks - to work out if this number is actually valid for a region,
1385
     * it should be parsed and methods such as {@link #isPossibleNumberWithReason} and
1386
     * {@link #isValidNumber} should be used.
1387
     *
1388
     * @param string $number the number that needs to be checked
1389
     * @return bool true if the number is a valid vanity number
1390
     */
1391 1
    public function isAlphaNumber($number)
1392
    {
1393 1
        if (!static::isViablePhoneNumber($number)) {
1394
            // Number is too short, or doesn't match the basic phone number pattern.
1395 1
            return false;
1396
        }
1397 1
        $this->maybeStripExtension($number);
1398 1
        return (bool)preg_match('/' . static::VALID_ALPHA_PHONE_PATTERN . '/' . static::REGEX_FLAGS, $number);
1399
    }
1400
1401
    /**
1402
     * Checks to see if the string of characters could possibly be a phone number at all. At the
1403
     * moment, checks to see that the string begins with at least 2 digits, ignoring any punctuation
1404
     * commonly found in phone numbers.
1405
     * This method does not require the number to be normalized in advance - but does assume that
1406
     * leading non-number symbols have been removed, such as by the method extractPossibleNumber.
1407
     *
1408
     * @param string $number to be checked for viability as a phone number
1409
     * @return boolean true if the number could be a phone number of some sort, otherwise false
1410
     */
1411 3271
    public static function isViablePhoneNumber($number)
1412
    {
1413 3271
        if (static::$VALID_PHONE_NUMBER_PATTERN === null) {
1414 2
            static::initValidPhoneNumberPatterns();
1415 2
        }
1416
1417 3271
        if (mb_strlen($number) < static::MIN_LENGTH_FOR_NSN) {
1418 25
            return false;
1419
        }
1420
1421 3270
        $validPhoneNumberPattern = static::getValidPhoneNumberPattern();
1422
1423 3270
        $m = preg_match($validPhoneNumberPattern, $number);
1424 3270
        return $m > 0;
1425
    }
1426
1427
    /**
1428
     * We append optionally the extension pattern to the end here, as a valid phone number may
1429
     * have an extension prefix appended, followed by 1 or more digits.
1430
     * @return string
1431
     */
1432 3270
    protected static function getValidPhoneNumberPattern()
1433
    {
1434 3270
        return static::$VALID_PHONE_NUMBER_PATTERN;
1435
    }
1436
1437
    /**
1438
     * Strips any extension (as in, the part of the number dialled after the call is connected,
1439
     * usually indicated with extn, ext, x or similar) from the end of the number, and returns it.
1440
     *
1441
     * @param string $number the non-normalized telephone number that we wish to strip the extension from
1442
     * @return string the phone extension
1443
     */
1444 3265
    protected function maybeStripExtension(&$number)
1445
    {
1446 3265
        $matches = array();
1447 3265
        $find = preg_match(static::$EXTN_PATTERN, $number, $matches, PREG_OFFSET_CAPTURE);
1448
        // If we find a potential extension, and the number preceding this is a viable number, we assume
1449
        // it is an extension.
1450 3265
        if ($find > 0 && static::isViablePhoneNumber(substr($number, 0, $matches[0][1]))) {
1451
            // The numbers are captured into groups in the regular expression.
1452
1453 29
            for ($i = 1, $length = count($matches); $i <= $length; $i++) {
1454 29
                if ($matches[$i][0] != '') {
1455
                    // We go through the capturing groups until we find one that captured some digits. If none
1456
                    // did, then we will return the empty string.
1457 29
                    $extension = $matches[$i][0];
1458 29
                    $number = substr($number, 0, $matches[0][1]);
1459 29
                    return $extension;
1460
                }
1461 29
            }
1462
        }
1463 3243
        return '';
1464
    }
1465
1466
    /**
1467
     * Parses a string and returns it in proto buffer format. This method differs from {@link #parse}
1468
     * in that it always populates the raw_input field of the protocol buffer with numberToParse as
1469
     * well as the country_code_source field.
1470
     *
1471
     * @param string $numberToParse number that we are attempting to parse. This can contain formatting
1472
     *                                  such as +, ( and -, as well as a phone number extension. It can also
1473
     *                                  be provided in RFC3966 format.
1474
     * @param string $defaultRegion region that we are expecting the number to be from. This is only used
1475
     *                                  if the number being parsed is not written in international format.
1476
     *                                  The country calling code for the number in this case would be stored
1477
     *                                  as that of the default region supplied.
1478
     * @param PhoneNumber $phoneNumber
1479
     * @return PhoneNumber              a phone number proto buffer filled with the parsed number
1480
     */
1481 182
    public function parseAndKeepRawInput($numberToParse, $defaultRegion, PhoneNumber $phoneNumber = null)
1482
    {
1483 182
        if ($phoneNumber === null) {
1484 182
            $phoneNumber = new PhoneNumber();
1485 182
        }
1486 182
        $this->parseHelper($numberToParse, $defaultRegion, true, true, $phoneNumber);
1487 181
        return $phoneNumber;
1488
    }
1489
1490
    /**
1491
     * Returns an iterable over all PhoneNumberMatches in $text
1492
     *
1493
     * @param string $text
1494
     * @param string $defaultRegion
1495
     * @param AbstractLeniency $leniency Defaults to Leniency::VALID()
1496
     * @param int $maxTries Defaults to PHP_INT_MAX
1497
     * @return PhoneNumberMatcher
1498
     */
1499 207
    public function findNumbers($text, $defaultRegion, AbstractLeniency $leniency = null, $maxTries = PHP_INT_MAX)
1500
    {
1501 207
        if ($leniency === null) {
1502 18
            $leniency = Leniency::VALID();
1503 18
        }
1504
1505 207
        return new PhoneNumberMatcher($this, $text, $defaultRegion, $leniency, $maxTries);
1506
    }
1507
1508
    /**
1509
     * Gets an AsYouTypeFormatter for the specific region.
1510
     *
1511
     * @param string $regionCode The region where the phone number is being entered.
1512
     * @return AsYouTypeFormatter
1513
     */
1514 33
    public function getAsYouTypeFormatter($regionCode)
1515
    {
1516 33
        return new AsYouTypeFormatter($regionCode);
1517
    }
1518
1519
    /**
1520
     * A helper function to set the values related to leading zeros in a PhoneNumber.
1521
     * @param string $nationalNumber
1522
     * @param PhoneNumber $phoneNumber
1523
     */
1524 3262
    public static function setItalianLeadingZerosForPhoneNumber($nationalNumber, PhoneNumber $phoneNumber)
1525
    {
1526 3262
        if (strlen($nationalNumber) > 1 && substr($nationalNumber, 0, 1) == '0') {
1527 125
            $phoneNumber->setItalianLeadingZero(true);
1528 125
            $numberOfLeadingZeros = 1;
1529
            // Note that if the national number is all "0"s, the last "0" is not counted as a leading
1530
            // zero.
1531 125
            while ($numberOfLeadingZeros < (strlen($nationalNumber) - 1) &&
1532 125
                substr($nationalNumber, $numberOfLeadingZeros, 1) == '0') {
1533 20
                $numberOfLeadingZeros++;
1534 20
            }
1535
1536 125
            if ($numberOfLeadingZeros != 1) {
1537 20
                $phoneNumber->setNumberOfLeadingZeros($numberOfLeadingZeros);
1538 20
            }
1539 125
        }
1540 3262
    }
1541
1542
    /**
1543
     * Parses a string and fills up the phoneNumber. This method is the same as the public
1544
     * parse() method, with the exception that it allows the default region to be null, for use by
1545
     * isNumberMatch(). checkRegion should be set to false if it is permitted for the default region
1546
     * to be null or unknown ("ZZ").
1547
     * @param string $numberToParse
1548
     * @param string $defaultRegion
1549
     * @param bool $keepRawInput
1550
     * @param bool $checkRegion
1551
     * @param PhoneNumber $phoneNumber
1552
     * @throws NumberParseException
1553
     */
1554 3268
    protected function parseHelper($numberToParse, $defaultRegion, $keepRawInput, $checkRegion, PhoneNumber $phoneNumber)
1555
    {
1556 3268
        if ($numberToParse === null) {
0 ignored issues
show
introduced by
The condition $numberToParse === null is always false.
Loading history...
1557 2
            throw new NumberParseException(NumberParseException::NOT_A_NUMBER, 'The phone number supplied was null.');
1558
        }
1559
1560 3267
        $numberToParse = trim($numberToParse);
1561
1562 3267
        if (mb_strlen($numberToParse) > static::MAX_INPUT_STRING_LENGTH) {
1563 1
            throw new NumberParseException(
1564 1
                NumberParseException::TOO_LONG,
1565
                'The string supplied was too long to parse.'
1566 1
            );
1567
        }
1568
1569 3266
        $nationalNumber = '';
1570 3266
        $this->buildNationalNumberForParsing($numberToParse, $nationalNumber);
1571
1572 3266
        if (!static::isViablePhoneNumber($nationalNumber)) {
1573 26
            throw new NumberParseException(
1574 26
                NumberParseException::NOT_A_NUMBER,
1575
                'The string supplied did not seem to be a phone number.'
1576 26
            );
1577
        }
1578
1579
        // Check the region supplied is valid, or that the extracted number starts with some sort of +
1580
        // sign so the number's region can be determined.
1581 3265
        if ($checkRegion && !$this->checkRegionForParsing($nationalNumber, $defaultRegion)) {
1582 7
            throw new NumberParseException(
1583 7
                NumberParseException::INVALID_COUNTRY_CODE,
1584
                'Missing or invalid default region.'
1585 7
            );
1586
        }
1587
1588 3264
        if ($keepRawInput) {
1589 181
            $phoneNumber->setRawInput($numberToParse);
1590 181
        }
1591
        // Attempt to parse extension first, since it doesn't require region-specific data and we want
1592
        // to have the non-normalised number here.
1593 3264
        $extension = $this->maybeStripExtension($nationalNumber);
1594 3264
        if (mb_strlen($extension) > 0) {
1595 28
            $phoneNumber->setExtension($extension);
1596 28
        }
1597
1598 3264
        $regionMetadata = $this->getMetadataForRegion($defaultRegion);
1599
        // Check to see if the number is given in international format so we know whether this number is
1600
        // from the default region or not.
1601 3264
        $normalizedNationalNumber = '';
1602
        try {
1603
            // TODO: This method should really just take in the string buffer that has already
1604
            // been created, and just remove the prefix, rather than taking in a string and then
1605
            // outputting a string buffer.
1606 3264
            $countryCode = $this->maybeExtractCountryCode(
1607 3264
                $nationalNumber,
1608 3264
                $regionMetadata,
1609 3264
                $normalizedNationalNumber,
1610 3264
                $keepRawInput,
1611
                $phoneNumber
1612 3264
            );
1613 3264
        } catch (NumberParseException $e) {
1614 15
            $matcher = new Matcher(static::$PLUS_CHARS_PATTERN, $nationalNumber);
1615 15
            if ($e->getErrorType() == NumberParseException::INVALID_COUNTRY_CODE && $matcher->lookingAt()) {
1616
                // Strip the plus-char, and try again.
1617 6
                $countryCode = $this->maybeExtractCountryCode(
1618 6
                    substr($nationalNumber, $matcher->end()),
1619 6
                    $regionMetadata,
1620 6
                    $normalizedNationalNumber,
1621 6
                    $keepRawInput,
1622
                    $phoneNumber
1623 6
                );
1624 6
                if ($countryCode == 0) {
1625 5
                    throw new NumberParseException(
1626 5
                        NumberParseException::INVALID_COUNTRY_CODE,
1627
                        'Could not interpret numbers after plus-sign.'
1628 5
                    );
1629
                }
1630 1
            } else {
1631 10
                throw new NumberParseException($e->getErrorType(), $e->getMessage(), $e);
1632
            }
1633
        }
1634 3264
        if ($countryCode !== 0) {
1635 346
            $phoneNumberRegion = $this->getRegionCodeForCountryCode($countryCode);
1636 346
            if ($phoneNumberRegion != $defaultRegion) {
1637
                // Metadata cannot be null because the country calling code is valid.
1638 286
                $regionMetadata = $this->getMetadataForRegionOrCallingCode($countryCode, $phoneNumberRegion);
1639 286
            }
1640 346
        } else {
1641
            // If no extracted country calling code, use the region supplied instead. The national number
1642
            // is just the normalized version of the number we were given to parse.
1643
1644 3195
            $normalizedNationalNumber .= static::normalize($nationalNumber);
1645 3195
            if ($defaultRegion !== null) {
0 ignored issues
show
introduced by
The condition $defaultRegion !== null is always true.
Loading history...
1646 3195
                $countryCode = $regionMetadata->getCountryCode();
1647 3195
                $phoneNumber->setCountryCode($countryCode);
1648 3195
            } elseif ($keepRawInput) {
1649
                $phoneNumber->clearCountryCodeSource();
1650
            }
1651
        }
1652 3264
        if (mb_strlen($normalizedNationalNumber) < static::MIN_LENGTH_FOR_NSN) {
1653 2
            throw new NumberParseException(
1654 2
                NumberParseException::TOO_SHORT_NSN,
1655
                'The string supplied is too short to be a phone number.'
1656 2
            );
1657
        }
1658 3263
        if ($regionMetadata !== null) {
1659 3263
            $carrierCode = '';
1660 3263
            $potentialNationalNumber = $normalizedNationalNumber;
1661 3263
            $this->maybeStripNationalPrefixAndCarrierCode($potentialNationalNumber, $regionMetadata, $carrierCode);
1662
            // We require that the NSN remaining after stripping the national prefix and carrier code be
1663
            // long enough to be a possible length for the region. Otherwise, we don't do the stripping,
1664
            // since the original number could be a valid short number.
1665 3263
            $validationResult = $this->testNumberLength($potentialNationalNumber, $regionMetadata);
1666
            if ($validationResult !== ValidationResult::TOO_SHORT
1667 3263
                && $validationResult !== ValidationResult::IS_POSSIBLE_LOCAL_ONLY
1668 3263
                && $validationResult !== ValidationResult::INVALID_LENGTH) {
1669 2100
                $normalizedNationalNumber = $potentialNationalNumber;
1670 2100
                if ($keepRawInput && mb_strlen($carrierCode) > 0) {
1671 1
                    $phoneNumber->setPreferredDomesticCarrierCode($carrierCode);
1672 1
                }
1673 2100
            }
1674 3263
        }
1675 3263
        $lengthOfNationalNumber = mb_strlen($normalizedNationalNumber);
1676 3263
        if ($lengthOfNationalNumber < static::MIN_LENGTH_FOR_NSN) {
1677
            throw new NumberParseException(
1678
                NumberParseException::TOO_SHORT_NSN,
1679
                'The string supplied is too short to be a phone number.'
1680
            );
1681
        }
1682 3263
        if ($lengthOfNationalNumber > static::MAX_LENGTH_FOR_NSN) {
1683 3
            throw new NumberParseException(
1684 3
                NumberParseException::TOO_LONG,
1685
                'The string supplied is too long to be a phone number.'
1686 3
            );
1687
        }
1688 3262
        static::setItalianLeadingZerosForPhoneNumber($normalizedNationalNumber, $phoneNumber);
1689
1690
        /*
1691
         * We have to store the National Number as a string instead of a "long" as Google do
1692
         *
1693
         * Since PHP doesn't always support 64 bit INTs, this was a float, but that had issues
1694
         * with long numbers.
1695
         *
1696
         * We have to remove the leading zeroes ourself though
1697
         */
1698 3262
        if ((int)$normalizedNationalNumber == 0) {
1699 29
            $normalizedNationalNumber = '0';
1700 29
        } else {
1701 3238
            $normalizedNationalNumber = ltrim($normalizedNationalNumber, '0');
1702
        }
1703
1704 3262
        $phoneNumber->setNationalNumber($normalizedNationalNumber);
1705 3262
    }
1706
1707
    /**
1708
     * Returns a new phone number containing only the fields needed to uniquely identify a phone
1709
     * number, rather than any fields that capture the context in which  the phone number was created.
1710
     * These fields correspond to those set in parse() rather than parseAndKeepRawInput()
1711
     *
1712
     * @param PhoneNumber $phoneNumberIn
1713
     * @return PhoneNumber
1714
     */
1715 8
    protected static function copyCoreFieldsOnly(PhoneNumber $phoneNumberIn)
1716
    {
1717 8
        $phoneNumber = new PhoneNumber();
1718 8
        $phoneNumber->setCountryCode($phoneNumberIn->getCountryCode());
1719 8
        $phoneNumber->setNationalNumber($phoneNumberIn->getNationalNumber());
1720 8
        if (mb_strlen($phoneNumberIn->getExtension()) > 0) {
1721 3
            $phoneNumber->setExtension($phoneNumberIn->getExtension());
1722 3
        }
1723 8
        if ($phoneNumberIn->isItalianLeadingZero()) {
1724 4
            $phoneNumber->setItalianLeadingZero(true);
1725
            // This field is only relevant if there are leading zeros at all.
1726 4
            $phoneNumber->setNumberOfLeadingZeros($phoneNumberIn->getNumberOfLeadingZeros());
1727 4
        }
1728 8
        return $phoneNumber;
1729
    }
1730
1731
    /**
1732
     * Converts numberToParse to a form that we can parse and write it to nationalNumber if it is
1733
     * written in RFC3966; otherwise extract a possible number out of it and write to nationalNumber.
1734
     * @param string $numberToParse
1735
     * @param string $nationalNumber
1736
     */
1737 3266
    protected function buildNationalNumberForParsing($numberToParse, &$nationalNumber)
1738
    {
1739 3266
        $indexOfPhoneContext = strpos($numberToParse, static::RFC3966_PHONE_CONTEXT);
1740 3266
        if ($indexOfPhoneContext !== false) {
1741 6
            $phoneContextStart = $indexOfPhoneContext + mb_strlen(static::RFC3966_PHONE_CONTEXT);
1742
            // If the phone context contains a phone number prefix, we need to capture it, whereas domains
1743
            // will be ignored.
1744 6
            if ($phoneContextStart < (strlen($numberToParse) - 1)
1745 6
                && substr($numberToParse, $phoneContextStart, 1) == static::PLUS_SIGN) {
1746
                // Additional parameters might follow the phone context. If so, we will remove them here
1747
                // because the parameters after phone context are not important for parsing the
1748
                // phone number.
1749 3
                $phoneContextEnd = strpos($numberToParse, ';', $phoneContextStart);
1750 3
                if ($phoneContextEnd > 0) {
1751 1
                    $nationalNumber .= substr($numberToParse, $phoneContextStart, $phoneContextEnd - $phoneContextStart);
1752 1
                } else {
1753 3
                    $nationalNumber .= substr($numberToParse, $phoneContextStart);
1754
                }
1755 3
            }
1756
1757
            // Now append everything between the "tel:" prefix and the phone-context. This should include
1758
            // the national number, an optional extension or isdn-subaddress component. Note we also
1759
            // handle the case when "tel:" is missing, as we have seen in some of the phone number inputs.
1760
            // In that case, we append everything from the beginning.
1761
1762 6
            $indexOfRfc3966Prefix = strpos($numberToParse, static::RFC3966_PREFIX);
1763 6
            $indexOfNationalNumber = ($indexOfRfc3966Prefix !== false) ? $indexOfRfc3966Prefix + strlen(static::RFC3966_PREFIX) : 0;
1764 6
            $nationalNumber .= substr($numberToParse, $indexOfNationalNumber,
1765 6
                $indexOfPhoneContext - $indexOfNationalNumber);
1766 6
        } else {
1767
            // Extract a possible number from the string passed in (this strips leading characters that
1768
            // could not be the start of a phone number.)
1769 3266
            $nationalNumber .= static::extractPossibleNumber($numberToParse);
0 ignored issues
show
Bug introduced by
$numberToParse of type string is incompatible with the type integer expected by parameter $number of libphonenumber\PhoneNumb...extractPossibleNumber(). ( Ignorable by Annotation )

If this is a false-positive, you can also ignore this issue in your code via the ignore-type  annotation

1769
            $nationalNumber .= static::extractPossibleNumber(/** @scrutinizer ignore-type */ $numberToParse);
Loading history...
1770
        }
1771
1772
        // Delete the isdn-subaddress and everything after it if it is present. Note extension won't
1773
        // appear at the same time with isdn-subaddress according to paragraph 5.3 of the RFC3966 spec,
1774 3266
        $indexOfIsdn = strpos($nationalNumber, static::RFC3966_ISDN_SUBADDRESS);
1775 3266
        if ($indexOfIsdn > 0) {
1776 5
            $nationalNumber = substr($nationalNumber, 0, $indexOfIsdn);
1777 5
        }
1778
        // If both phone context and isdn-subaddress are absent but other parameters are present, the
1779
        // parameters are left in nationalNumber. This is because we are concerned about deleting
1780
        // content from a potential number string when there is no strong evidence that the number is
1781
        // actually written in RFC3966.
1782 3266
    }
1783
1784
    /**
1785
     * Attempts to extract a possible number from the string passed in. This currently strips all
1786
     * leading characters that cannot be used to start a phone number. Characters that can be used to
1787
     * start a phone number are defined in the VALID_START_CHAR_PATTERN. If none of these characters
1788
     * are found in the number passed in, an empty string is returned. This function also attempts to
1789
     * strip off any alternative extensions or endings if two or more are present, such as in the case
1790
     * of: (530) 583-6985 x302/x2303. The second extension here makes this actually two phone numbers,
1791
     * (530) 583-6985 x302 and (530) 583-6985 x2303. We remove the second extension so that the first
1792
     * number is parsed correctly.
1793
     *
1794
     * @param int $number the string that might contain a phone number
1795
     * @return string the number, stripped of any non-phone-number prefix (such as "Tel:") or an empty
1796
     *                string if no character used to start phone numbers (such as + or any digit) is
1797
     *                found in the number
1798
     */
1799 3289
    public static function extractPossibleNumber($number)
1800
    {
1801 3289
        if (static::$VALID_START_CHAR_PATTERN === null) {
1802 1
            static::initValidStartCharPattern();
1803 1
        }
1804
1805 3289
        $matches = array();
1806 3289
        $match = preg_match('/' . static::$VALID_START_CHAR_PATTERN . '/ui', $number, $matches, PREG_OFFSET_CAPTURE);
1807 3289
        if ($match > 0) {
1808 3289
            $number = substr($number, $matches[0][1]);
1809
            // Remove trailing non-alpha non-numerical characters.
1810 3289
            $trailingCharsMatcher = new Matcher(static::$UNWANTED_END_CHAR_PATTERN, $number);
1811 3289
            if ($trailingCharsMatcher->find() && $trailingCharsMatcher->start() > 0) {
1812 2
                $number = substr($number, 0, $trailingCharsMatcher->start());
1813 2
            }
1814
1815
            // Check for extra numbers at the end.
1816 3289
            $match = preg_match('%' . static::$SECOND_NUMBER_START_PATTERN . '%', $number, $matches, PREG_OFFSET_CAPTURE);
1817 3289
            if ($match > 0) {
1818 1
                $number = substr($number, 0, $matches[0][1]);
1819 1
            }
1820
1821 3289
            return $number;
1822
        }
1823
1824 6
        return '';
1825
    }
1826
1827
    /**
1828
     * Checks to see that the region code used is valid, or if it is not valid, that the number to
1829
     * parse starts with a + symbol so that we can attempt to infer the region from the number.
1830
     * Returns false if it cannot use the region provided and the region cannot be inferred.
1831
     * @param string $numberToParse
1832
     * @param string $defaultRegion
1833
     * @return bool
1834
     */
1835 3265
    protected function checkRegionForParsing($numberToParse, $defaultRegion)
1836
    {
1837 3265
        if (!$this->isValidRegionCode($defaultRegion)) {
1838
            // If the number is null or empty, we can't infer the region.
1839 273
            $plusCharsPatternMatcher = new Matcher(static::$PLUS_CHARS_PATTERN, $numberToParse);
1840 273
            if ($numberToParse === null || mb_strlen($numberToParse) == 0 || !$plusCharsPatternMatcher->lookingAt()) {
1841 7
                return false;
1842
            }
1843 270
        }
1844 3264
        return true;
1845
    }
1846
1847
    /**
1848
     * Tries to extract a country calling code from a number. This method will return zero if no
1849
     * country calling code is considered to be present. Country calling codes are extracted in the
1850
     * following ways:
1851
     * <ul>
1852
     *  <li> by stripping the international dialing prefix of the region the person is dialing from,
1853
     *       if this is present in the number, and looking at the next digits
1854
     *  <li> by stripping the '+' sign if present and then looking at the next digits
1855
     *  <li> by comparing the start of the number and the country calling code of the default region.
1856
     *       If the number is not considered possible for the numbering plan of the default region
1857
     *       initially, but starts with the country calling code of this region, validation will be
1858
     *       reattempted after stripping this country calling code. If this number is considered a
1859
     *       possible number, then the first digits will be considered the country calling code and
1860
     *       removed as such.
1861
     * </ul>
1862
     * It will throw a NumberParseException if the number starts with a '+' but the country calling
1863
     * code supplied after this does not match that of any known region.
1864
     *
1865
     * @param string $number non-normalized telephone number that we wish to extract a country calling
1866
     *     code from - may begin with '+'
1867
     * @param PhoneMetadata $defaultRegionMetadata metadata about the region this number may be from
1868
     * @param string $nationalNumber a string buffer to store the national significant number in, in the case
1869
     *     that a country calling code was extracted. The number is appended to any existing contents.
1870
     *     If no country calling code was extracted, this will be left unchanged.
1871
     * @param bool $keepRawInput true if the country_code_source and preferred_carrier_code fields of
1872
     *     phoneNumber should be populated.
1873
     * @param PhoneNumber $phoneNumber the PhoneNumber object where the country_code and country_code_source need
1874
     *     to be populated. Note the country_code is always populated, whereas country_code_source is
1875
     *     only populated when keepCountryCodeSource is true.
1876
     * @return int the country calling code extracted or 0 if none could be extracted
1877
     * @throws NumberParseException
1878
     */
1879 3265
    public function maybeExtractCountryCode(
1880
        $number,
1881
        PhoneMetadata $defaultRegionMetadata = null,
1882
        &$nationalNumber,
1883
        $keepRawInput,
1884
        PhoneNumber $phoneNumber
1885
    ) {
1886 3265
        if (mb_strlen($number) == 0) {
1887
            return 0;
1888
        }
1889 3265
        $fullNumber = $number;
1890
        // Set the default prefix to be something that will never match.
1891 3265
        $possibleCountryIddPrefix = 'NonMatch';
1892 3265
        if ($defaultRegionMetadata !== null) {
1893 3248
            $possibleCountryIddPrefix = $defaultRegionMetadata->getInternationalPrefix();
1894 3248
        }
1895 3265
        $countryCodeSource = $this->maybeStripInternationalPrefixAndNormalize($fullNumber, $possibleCountryIddPrefix);
1896
1897 3265
        if ($keepRawInput) {
1898 182
            $phoneNumber->setCountryCodeSource($countryCodeSource);
1899 182
        }
1900 3265
        if ($countryCodeSource != CountryCodeSource::FROM_DEFAULT_COUNTRY) {
1901 339
            if (mb_strlen($fullNumber) <= static::MIN_LENGTH_FOR_NSN) {
1902 10
                throw new NumberParseException(
1903 10
                    NumberParseException::TOO_SHORT_AFTER_IDD,
1904
                    'Phone number had an IDD, but after this was not long enough to be a viable phone number.'
1905 10
                );
1906
            }
1907 338
            $potentialCountryCode = $this->extractCountryCode($fullNumber, $nationalNumber);
1908
1909 338
            if ($potentialCountryCode != 0) {
1910 338
                $phoneNumber->setCountryCode($potentialCountryCode);
1911 338
                return $potentialCountryCode;
1912
            }
1913
1914
            // If this fails, they must be using a strange country calling code that we don't recognize,
1915
            // or that doesn't exist.
1916 8
            throw new NumberParseException(
1917 8
                NumberParseException::INVALID_COUNTRY_CODE,
1918
                'Country calling code supplied was not recognised.'
1919 8
            );
1920
        }
1921
1922 3206
        if ($defaultRegionMetadata !== null) {
1923
            // Check to see if the number starts with the country calling code for the default region. If
1924
            // so, we remove the country calling code, and do some checks on the validity of the number
1925
            // before and after.
1926 3206
            $defaultCountryCode = $defaultRegionMetadata->getCountryCode();
1927 3206
            $defaultCountryCodeString = (string)$defaultCountryCode;
1928 3206
            $normalizedNumber = $fullNumber;
1929 3206
            if (strpos($normalizedNumber, $defaultCountryCodeString) === 0) {
1930 106
                $potentialNationalNumber = substr($normalizedNumber, mb_strlen($defaultCountryCodeString));
1931 106
                $generalDesc = $defaultRegionMetadata->getGeneralDesc();
1932
                // Don't need the carrier code.
1933 106
                $carriercode = null;
1934 106
                $this->maybeStripNationalPrefixAndCarrierCode(
1935 106
                    $potentialNationalNumber,
1936 106
                    $defaultRegionMetadata,
1937
                    $carriercode
1938 106
                );
1939
                // If the number was not valid before but is valid now, or if it was too long before, we
1940
                // consider the number with the country calling code stripped to be a better result and
1941
                // keep that instead.
1942 106
                if ((!$this->matcherAPI->matchNationalNumber($fullNumber, $generalDesc, false)
1943 106
                        && $this->matcherAPI->matchNationalNumber($potentialNationalNumber, $generalDesc, false))
1944 92
                    || $this->testNumberLength($fullNumber, $defaultRegionMetadata) === ValidationResult::TOO_LONG
1945 106
                ) {
1946 24
                    $nationalNumber .= $potentialNationalNumber;
1947 24
                    if ($keepRawInput) {
1948 15
                        $phoneNumber->setCountryCodeSource(CountryCodeSource::FROM_NUMBER_WITHOUT_PLUS_SIGN);
1949 15
                    }
1950 24
                    $phoneNumber->setCountryCode($defaultCountryCode);
1951 24
                    return $defaultCountryCode;
1952
                }
1953 91
            }
1954 3196
        }
1955
        // No country calling code present.
1956 3196
        $phoneNumber->setCountryCode(0);
1957 3196
        return 0;
1958
    }
1959
1960
    /**
1961
     * Strips any international prefix (such as +, 00, 011) present in the number provided, normalizes
1962
     * the resulting number, and indicates if an international prefix was present.
1963
     *
1964
     * @param string $number the non-normalized telephone number that we wish to strip any international
1965
     *     dialing prefix from.
1966
     * @param string $possibleIddPrefix string the international direct dialing prefix from the region we
1967
     *     think this number may be dialed in
1968
     * @return int the corresponding CountryCodeSource if an international dialing prefix could be
1969
     *     removed from the number, otherwise CountryCodeSource.FROM_DEFAULT_COUNTRY if the number did
1970
     *     not seem to be in international format.
1971
     */
1972 3266
    public function maybeStripInternationalPrefixAndNormalize(&$number, $possibleIddPrefix)
1973
    {
1974 3266
        if (mb_strlen($number) == 0) {
1975
            return CountryCodeSource::FROM_DEFAULT_COUNTRY;
1976
        }
1977 3266
        $matches = array();
1978
        // Check to see if the number begins with one or more plus signs.
1979 3266
        $match = preg_match('/^' . static::$PLUS_CHARS_PATTERN . '/' . static::REGEX_FLAGS, $number, $matches, PREG_OFFSET_CAPTURE);
1980 3266
        if ($match > 0) {
1981 337
            $number = mb_substr($number, $matches[0][1] + mb_strlen($matches[0][0]));
1982
            // Can now normalize the rest of the number since we've consumed the "+" sign at the start.
1983 337
            $number = static::normalize($number);
1984 337
            return CountryCodeSource::FROM_NUMBER_WITH_PLUS_SIGN;
1985
        }
1986
        // Attempt to parse the first digits as an international prefix.
1987 3208
        $iddPattern = $possibleIddPrefix;
1988 3208
        $number = static::normalize($number);
1989 3208
        return $this->parsePrefixAsIdd($iddPattern, $number)
1990 3208
            ? CountryCodeSource::FROM_NUMBER_WITH_IDD
1991 3208
            : CountryCodeSource::FROM_DEFAULT_COUNTRY;
1992
    }
1993
1994
    /**
1995
     * Normalizes a string of characters representing a phone number. This performs
1996
     * the following conversions:
1997
     *   Punctuation is stripped.
1998
     *   For ALPHA/VANITY numbers:
1999
     *   Letters are converted to their numeric representation on a telephone
2000
     *       keypad. The keypad used here is the one defined in ITU Recommendation
2001
     *       E.161. This is only done if there are 3 or more letters in the number,
2002
     *       to lessen the risk that such letters are typos.
2003
     *   For other numbers:
2004
     *    - Wide-ascii digits are converted to normal ASCII (European) digits.
2005
     *    - Arabic-Indic numerals are converted to European numerals.
2006
     *    - Spurious alpha characters are stripped.
2007
     *
2008
     * @param string $number a string of characters representing a phone number.
2009
     * @return string the normalized string version of the phone number.
2010
     */
2011 3270
    public static function normalize(&$number)
2012
    {
2013 3270
        if (static::$ALPHA_PHONE_MAPPINGS === null) {
0 ignored issues
show
introduced by
The condition static::ALPHA_PHONE_MAPPINGS === null is always false.
Loading history...
2014 1
            static::initAlphaPhoneMappings();
2015 1
        }
2016
2017 3270
        $m = new Matcher(static::VALID_ALPHA_PHONE_PATTERN, $number);
2018 3270
        if ($m->matches()) {
2019 8
            return static::normalizeHelper($number, static::$ALPHA_PHONE_MAPPINGS, true);
2020
        }
2021
2022 3268
        return static::normalizeDigitsOnly($number);
2023
    }
2024
2025
    /**
2026
     * Normalizes a string of characters representing a phone number. This converts wide-ascii and
2027
     * arabic-indic numerals to European numerals, and strips punctuation and alpha characters.
2028
     *
2029
     * @param $number string  a string of characters representing a phone number
2030
     * @return string the normalized string version of the phone number
2031
     */
2032 3289
    public static function normalizeDigitsOnly($number)
2033
    {
2034 3289
        return static::normalizeDigits($number, false /* strip non-digits */);
2035
    }
2036
2037
    /**
2038
     * @param string $number
2039
     * @param bool $keepNonDigits
2040
     * @return string
2041
     */
2042 3322
    public static function normalizeDigits($number, $keepNonDigits)
2043
    {
2044 3322
        $normalizedDigits = '';
2045 3322
        $numberAsArray = preg_split('/(?<!^)(?!$)/u', $number);
2046 3322
        foreach ($numberAsArray as $character) {
2047
            // Check if we are in the unicode number range
2048 3322
            if (array_key_exists($character, static::$numericCharacters)) {
2049 6
                $normalizedDigits .= static::$numericCharacters[$character];
2050 3322
            } elseif (is_numeric($character)) {
2051 3319
                $normalizedDigits .= $character;
2052 3320
            } elseif ($keepNonDigits) {
2053 50
                $normalizedDigits .= $character;
2054 50
            }
2055 3322
        }
2056 3322
        return $normalizedDigits;
2057
    }
2058
2059
    /**
2060
     * Strips the IDD from the start of the number if present. Helper function used by
2061
     * maybeStripInternationalPrefixAndNormalize.
2062
     * @param string $iddPattern
2063
     * @param string $number
2064
     * @return bool
2065
     */
2066 3208
    protected function parsePrefixAsIdd($iddPattern, &$number)
2067
    {
2068 3208
        $m = new Matcher($iddPattern, $number);
2069 3208
        if ($m->lookingAt()) {
2070 22
            $matchEnd = $m->end();
2071
            // Only strip this if the first digit after the match is not a 0, since country calling codes
2072
            // cannot begin with 0.
2073 22
            $digitMatcher = new Matcher(static::$CAPTURING_DIGIT_PATTERN, substr($number, $matchEnd));
2074 22
            if ($digitMatcher->find()) {
2075 22
                $normalizedGroup = static::normalizeDigitsOnly($digitMatcher->group(1));
2076 22
                if ($normalizedGroup == '0') {
2077 7
                    return false;
2078
                }
2079 19
            }
2080 19
            $number = substr($number, $matchEnd);
2081 19
            return true;
2082
        }
2083 3204
        return false;
2084
    }
2085
2086
    /**
2087
     * Extracts country calling code from fullNumber, returns it and places the remaining number in  nationalNumber.
2088
     * It assumes that the leading plus sign or IDD has already been removed.
2089
     * Returns 0 if fullNumber doesn't start with a valid country calling code, and leaves nationalNumber unmodified.
2090
     * @param string $fullNumber
2091
     * @param string $nationalNumber
2092
     * @return int
2093
     * @internal
2094
     */
2095 356
    public function extractCountryCode($fullNumber, &$nationalNumber)
2096
    {
2097 356
        if ((mb_strlen($fullNumber) == 0) || ($fullNumber[0] == '0')) {
2098
            // Country codes do not begin with a '0'.
2099 2
            return 0;
2100
        }
2101 356
        $numberLength = mb_strlen($fullNumber);
2102 356
        for ($i = 1; $i <= static::MAX_LENGTH_COUNTRY_CODE && $i <= $numberLength; $i++) {
2103 356
            $potentialCountryCode = (int)substr($fullNumber, 0, $i);
2104 356
            if (isset($this->countryCallingCodeToRegionCodeMap[$potentialCountryCode])) {
2105 356
                $nationalNumber .= substr($fullNumber, $i);
2106 356
                return $potentialCountryCode;
2107
            }
2108 314
        }
2109 11
        return 0;
2110
    }
2111
2112
    /**
2113
     * Strips any national prefix (such as 0, 1) present in the number provided.
2114
     *
2115
     * @param string $number the normalized telephone number that we wish to strip any national
2116
     *     dialing prefix from
2117
     * @param PhoneMetadata $metadata the metadata for the region that we think this number is from
2118
     * @param string $carrierCode a place to insert the carrier code if one is extracted
2119
     * @return bool true if a national prefix or carrier code (or both) could be extracted.
2120
     */
2121 3265
    public function maybeStripNationalPrefixAndCarrierCode(&$number, PhoneMetadata $metadata, &$carrierCode)
2122
    {
2123 3265
        $numberLength = mb_strlen($number);
2124 3265
        $possibleNationalPrefix = $metadata->getNationalPrefixForParsing();
2125 3265
        if ($numberLength == 0 || $possibleNationalPrefix === null || mb_strlen($possibleNationalPrefix) == 0) {
2126
            // Early return for numbers of zero length.
2127 1101
            return false;
2128
        }
2129
2130
        // Attempt to parse the first digits as a national prefix.
2131 2174
        $prefixMatcher = new Matcher($possibleNationalPrefix, $number);
2132 2174
        if ($prefixMatcher->lookingAt()) {
2133 169
            $generalDesc = $metadata->getGeneralDesc();
2134
            // Check if the original number is viable.
2135 169
            $isViableOriginalNumber = $this->matcherAPI->matchNationalNumber($number, $generalDesc, false);
2136
            // $prefixMatcher->group($numOfGroups) === null implies nothing was captured by the capturing
2137
            // groups in $possibleNationalPrefix; therefore, no transformation is necessary, and we just
2138
            // remove the national prefix
2139 169
            $numOfGroups = $prefixMatcher->groupCount();
2140 169
            $transformRule = $metadata->getNationalPrefixTransformRule();
2141
            if ($transformRule === null
2142 169
                || mb_strlen($transformRule) == 0
2143 47
                || $prefixMatcher->group($numOfGroups - 1) === null
2144 169
            ) {
2145
                // If the original number was viable, and the resultant number is not, we return.
2146 167
                if ($isViableOriginalNumber &&
2147 65
                    !$this->matcherAPI->matchNationalNumber(
2148 167
                        substr($number, $prefixMatcher->end()), $generalDesc, false)) {
2149 16
                    return false;
2150
                }
2151 155
                if ($carrierCode !== null && $numOfGroups > 0 && $prefixMatcher->group($numOfGroups) !== null) {
2152 2
                    $carrierCode .= $prefixMatcher->group(1);
2153 2
                }
2154
2155 155
                $number = substr($number, $prefixMatcher->end());
2156 155
                return true;
2157
            }
2158
2159
            // Check that the resultant number is still viable. If not, return. Check this by copying
2160
            // the string and making the transformation on the copy first.
2161 8
            $transformedNumber = $number;
2162 8
            $transformedNumber = substr_replace(
2163 8
                $transformedNumber,
2164 8
                $prefixMatcher->replaceFirst($transformRule),
2165 8
                0,
2166
                $numberLength
2167 8
            );
2168
            if ($isViableOriginalNumber
2169 8
                && !$this->matcherAPI->matchNationalNumber($transformedNumber, $generalDesc, false)) {
2170
                return false;
2171
            }
2172 8
            if ($carrierCode !== null && $numOfGroups > 1) {
2173
                $carrierCode .= $prefixMatcher->group(1);
2174
            }
2175 8
            $number = substr_replace($number, $transformedNumber, 0, mb_strlen($number));
2176 8
            return true;
2177
        }
2178 2060
        return false;
2179
    }
2180
2181
    /**
2182
     * Convenience wrapper around isPossibleNumberForTypeWithReason. Instead of returning the reason
2183
     * reason for failure, this method returns true if the number is either a possible fully-qualified
2184
     * number (containing the area code and country code), or if the number could be a possible local
2185
     * number (with a country code, but missing an area code). Local numbers are considered possible
2186
     * if they could be possibly dialled in this format: if the area code is needed for a call to
2187
     * connect, the number is not considered possible without it.
2188
     *
2189
     * @param PhoneNumber $number The number that needs to be checked
2190
     * @param int $type PhoneNumberType The type we are interested in
2191
     * @return bool true if the number is possible for this particular type
2192
     */
2193 4
    public function isPossibleNumberForType(PhoneNumber $number, $type)
2194
    {
2195 4
        $result = $this->isPossibleNumberForTypeWithReason($number, $type);
2196
        return $result === ValidationResult::IS_POSSIBLE
2197 4
            || $result === ValidationResult::IS_POSSIBLE_LOCAL_ONLY;
2198
    }
2199
2200
    /**
2201
     * Helper method to check a number against possible lengths for this number type, and determine
2202
     * whether it matches, or is too short or too long.
2203
     *
2204
     * @param string $number
2205
     * @param PhoneMetadata $metadata
2206
     * @param int $type PhoneNumberType
2207
     * @return int ValidationResult
2208
     */
2209 3276
    protected function testNumberLength($number, PhoneMetadata $metadata, $type = PhoneNumberType::UNKNOWN)
2210
    {
2211 3276
        $descForType = $this->getNumberDescByType($metadata, $type);
2212
        // There should always be "possibleLengths" set for every element. This is declared in the XML
2213
        // schema which is verified by PhoneNumberMetadataSchemaTest.
2214
        // For size efficiency, where a sub-description (e.g. fixed-line) has the same possibleLengths
2215
        // as the parent, this is missing, so we fall back to the general desc (where no numbers of the
2216
        // type exist at all, there is one possible length (-1) which is guaranteed not to match the
2217
        // length of any real phone number).
2218 3276
        $possibleLengths = (count($descForType->getPossibleLength()) === 0)
2219 3276
            ? $metadata->getGeneralDesc()->getPossibleLength() : $descForType->getPossibleLength();
2220
2221 3276
        $localLengths = $descForType->getPossibleLengthLocalOnly();
2222
2223 3276
        if ($type === PhoneNumberType::FIXED_LINE_OR_MOBILE) {
2224 3
            if (!static::descHasPossibleNumberData($this->getNumberDescByType($metadata, PhoneNumberType::FIXED_LINE))) {
2225
                // The rate case has been encountered where no fixedLine data is available (true for some
2226
                // non-geographical entities), so we just check mobile.
2227 2
                return $this->testNumberLength($number, $metadata, PhoneNumberType::MOBILE);
2228
            }
2229
2230 3
            $mobileDesc = $this->getNumberDescByType($metadata, PhoneNumberType::MOBILE);
2231 3
            if (static::descHasPossibleNumberData($mobileDesc)) {
2232
                // Note that when adding the possible lengths from mobile, we have to again check they
2233
                // aren't empty since if they are this indicates they are the same as the general desc and
2234
                // should be obtained from there.
2235 1
                $possibleLengths = array_merge($possibleLengths,
2236 1
                    (count($mobileDesc->getPossibleLength()) === 0)
2237 1
                        ? $metadata->getGeneralDesc()->getPossibleLength() : $mobileDesc->getPossibleLength());
2238
2239
                // The current list is sorted; we need to merge in the new list and re-sort (duplicates
2240
                // are okay). Sorting isn't so expensive because the lists are very small.
2241 1
                sort($possibleLengths);
2242
2243 1
                if (count($localLengths) === 0) {
2244 1
                    $localLengths = $mobileDesc->getPossibleLengthLocalOnly();
2245 1
                } else {
2246
                    $localLengths = array_merge($localLengths, $mobileDesc->getPossibleLengthLocalOnly());
2247
                    sort($localLengths);
2248
                }
2249 1
            }
2250 3
        }
2251
2252
2253
        // If the type is not supported at all (indicated by the possible lengths containing -1 at this
2254
        // point) we return invalid length.
2255
2256 3276
        if ($possibleLengths[0] === -1) {
2257 2
            return ValidationResult::INVALID_LENGTH;
2258
        }
2259
2260 3276
        $actualLength = mb_strlen($number);
2261
2262
        // This is safe because there is never an overlap between the possible lengths and the local-only
2263
        // lengths; this is checked at build time.
2264
2265 3276
        if (in_array($actualLength, $localLengths)) {
2266 77
            return ValidationResult::IS_POSSIBLE_LOCAL_ONLY;
2267
        }
2268
2269 3228
        $minimumLength = reset($possibleLengths);
2270 3228
        if ($minimumLength == $actualLength) {
2271 1338
            return ValidationResult::IS_POSSIBLE;
2272
        }
2273
2274 1948
        if ($minimumLength > $actualLength) {
2275 1145
            return ValidationResult::TOO_SHORT;
2276 828
        } elseif (isset($possibleLengths[count($possibleLengths) - 1]) && $possibleLengths[count($possibleLengths) - 1] < $actualLength) {
2277 31
            return ValidationResult::TOO_LONG;
2278
        }
2279
2280
        // We skip the first element; we've already checked it.
2281 814
        array_shift($possibleLengths);
2282 814
        return in_array($actualLength, $possibleLengths) ? ValidationResult::IS_POSSIBLE : ValidationResult::INVALID_LENGTH;
2283
    }
2284
2285
    /**
2286
     * Returns a list with the region codes that match the specific country calling code. For
2287
     * non-geographical country calling codes, the region code 001 is returned. Also, in the case
2288
     * of no region code being found, an empty list is returned.
2289
     * @param int $countryCallingCode
2290
     * @return array
2291
     */
2292 10
    public function getRegionCodesForCountryCode($countryCallingCode)
2293
    {
2294 10
        $regionCodes = isset($this->countryCallingCodeToRegionCodeMap[$countryCallingCode]) ? $this->countryCallingCodeToRegionCodeMap[$countryCallingCode] : null;
2295 10
        return $regionCodes === null ? array() : $regionCodes;
2296
    }
2297
2298
    /**
2299
     * Returns the country calling code for a specific region. For example, this would be 1 for the
2300
     * United States, and 64 for New Zealand. Assumes the region is already valid.
2301
     *
2302
     * @param string $regionCode the region that we want to get the country calling code for
2303
     * @return int the country calling code for the region denoted by regionCode
2304
     */
2305 37
    public function getCountryCodeForRegion($regionCode)
2306
    {
2307 37
        if (!$this->isValidRegionCode($regionCode)) {
2308 4
            return 0;
2309
        }
2310 37
        return $this->getCountryCodeForValidRegion($regionCode);
2311
    }
2312
2313
    /**
2314
     * Returns the country calling code for a specific region. For example, this would be 1 for the
2315
     * United States, and 64 for New Zealand. Assumes the region is already valid.
2316
     *
2317
     * @param string $regionCode the region that we want to get the country calling code for
2318
     * @return int the country calling code for the region denoted by regionCode
2319
     * @throws \InvalidArgumentException if the region is invalid
2320
     */
2321 1993
    protected function getCountryCodeForValidRegion($regionCode)
2322
    {
2323 1993
        $metadata = $this->getMetadataForRegion($regionCode);
2324 1993
        if ($metadata === null) {
2325
            throw new \InvalidArgumentException('Invalid region code: ' . $regionCode);
2326
        }
2327 1993
        return $metadata->getCountryCode();
2328
    }
2329
2330
    /**
2331
     * Returns a number formatted in such a way that it can be dialed from a mobile phone in a
2332
     * specific region. If the number cannot be reached from the region (e.g. some countries block
2333
     * toll-free numbers from being called outside of the country), the method returns an empty
2334
     * string.
2335
     *
2336
     * @param PhoneNumber $number the phone number to be formatted
2337
     * @param string $regionCallingFrom the region where the call is being placed
2338
     * @param boolean $withFormatting whether the number should be returned with formatting symbols, such as
2339
     *     spaces and dashes.
2340
     * @return string the formatted phone number
2341
     */
2342 1
    public function formatNumberForMobileDialing(PhoneNumber $number, $regionCallingFrom, $withFormatting)
2343
    {
2344 1
        $countryCallingCode = $number->getCountryCode();
2345 1
        if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
2346
            return $number->hasRawInput() ? $number->getRawInput() : '';
2347
        }
2348
2349 1
        $formattedNumber = '';
2350
        // Clear the extension, as that part cannot normally be dialed together with the main number.
2351 1
        $numberNoExt = new PhoneNumber();
2352 1
        $numberNoExt->mergeFrom($number)->clearExtension();
2353 1
        $regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
2354 1
        $numberType = $this->getNumberType($numberNoExt);
2355 1
        $isValidNumber = ($numberType !== PhoneNumberType::UNKNOWN);
2356 1
        if ($regionCallingFrom == $regionCode) {
2357 1
            $isFixedLineOrMobile = ($numberType == PhoneNumberType::FIXED_LINE) || ($numberType == PhoneNumberType::MOBILE) || ($numberType == PhoneNumberType::FIXED_LINE_OR_MOBILE);
2358
            // Carrier codes may be needed in some countries. We handle this here.
2359 1
            if ($regionCode == 'CO' && $numberType == PhoneNumberType::FIXED_LINE) {
2360
                $formattedNumber = $this->formatNationalNumberWithCarrierCode(
2361
                    $numberNoExt,
2362
                    static::COLOMBIA_MOBILE_TO_FIXED_LINE_PREFIX
2363
                );
2364 1
            } elseif ($regionCode == 'BR' && $isFixedLineOrMobile) {
2365
                // Historically, we set this to an empty string when parsing with raw input if none was
2366
                // found in the input string. However, this doesn't result in a number we can dial. For this
2367
                // reason, we treat the empty string the same as if it isn't set at all.
2368
                $formattedNumber = mb_strlen($numberNoExt->getPreferredDomesticCarrierCode()) > 0
2369
                    ? $this->formatNationalNumberWithPreferredCarrierCode($numberNoExt, '')
2370
                    // Brazilian fixed line and mobile numbers need to be dialed with a carrier code when
2371
                    // called within Brazil. Without that, most of the carriers won't connect the call.
2372
                    // Because of that, we return an empty string here.
2373
                    : '';
2374 1
            } elseif ($countryCallingCode === static::NANPA_COUNTRY_CODE) {
2375
                // For NANPA countries, we output international format for numbers that can be dialed
2376
                // internationally, since that always works, except for numbers which might potentially be
2377
                // short numbers, which are always dialled in national format.
2378 1
                $regionMetadata = $this->getMetadataForRegion($regionCallingFrom);
2379 1
                if ($this->canBeInternationallyDialled($numberNoExt)
2380 1
                    && $this->testNumberLength($this->getNationalSignificantNumber($numberNoExt), $regionMetadata)
2381
                    !== ValidationResult::TOO_SHORT
2382 1
                ) {
2383 1
                    $formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::INTERNATIONAL);
2384 1
                } else {
2385 1
                    $formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::NATIONAL);
2386
                }
2387 1
            } elseif (($regionCode == static::REGION_CODE_FOR_NON_GEO_ENTITY ||
0 ignored issues
show
introduced by
Consider adding parentheses for clarity. Current Interpretation: ($regionCode == static::...lyDialled($numberNoExt), Probably Intended Meaning: $regionCode == static::R...yDialled($numberNoExt))
Loading history...
2388
                    // MX fixed line and mobile numbers should always be formatted in international format,
2389
                    // even when dialed within MX. For national format to work, a carrier code needs to be
2390
                    // used, and the correct carrier code depends on if the caller and callee are from the
2391
                    // same local area. It is trickier to get that to work correctly than using
2392
                    // international format, which is tested to work fine on all carriers.
2393
                    // CL fixed line numbers need the national prefix when dialing in the national format,
2394
                    // but don't have it when used for display. The reverse is true for mobile numbers.
2395
                    // As a result, we output them in the international format to make it work.
2396
                    (
2397 1
                        ($regionCode === 'MX' || $regionCode === 'CL' || $regionCode === 'UZ')
2398 1
                        && $isFixedLineOrMobile
2399 1
                    )
2400 1
                ) && $this->canBeInternationallyDialled($numberNoExt)
2401 1
            ) {
2402 1
                $formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::INTERNATIONAL);
2403 1
            } else {
2404 1
                $formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::NATIONAL);
2405
            }
2406 1
        } elseif ($isValidNumber && $this->canBeInternationallyDialled($numberNoExt)) {
2407
            // We assume that short numbers are not diallable from outside their region, so if a number
2408
            // is not a valid regular length phone number, we treat it as if it cannot be internationally
2409
            // dialled.
2410
            return $withFormatting ?
2411 1
                $this->format($numberNoExt, PhoneNumberFormat::INTERNATIONAL) :
2412 1
                $this->format($numberNoExt, PhoneNumberFormat::E164);
2413
        }
2414 1
        return $withFormatting ? $formattedNumber : static::normalizeDiallableCharsOnly($formattedNumber);
2415
    }
2416
2417
    /**
2418
     * Formats a phone number in national format for dialing using the carrier as specified in the
2419
     * {@code carrierCode}. The {@code carrierCode} will always be used regardless of whether the
2420
     * phone number already has a preferred domestic carrier code stored. If {@code carrierCode}
2421
     * contains an empty string, returns the number in national format without any carrier code.
2422
     *
2423
     * @param PhoneNumber $number the phone number to be formatted
2424
     * @param string $carrierCode the carrier selection code to be used
2425
     * @return string the formatted phone number in national format for dialing using the carrier as
2426
     * specified in the {@code carrierCode}
2427
     */
2428 2
    public function formatNationalNumberWithCarrierCode(PhoneNumber $number, $carrierCode)
2429
    {
2430 2
        $countryCallingCode = $number->getCountryCode();
2431 2
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
2432 2
        if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
2433 1
            return $nationalSignificantNumber;
2434
        }
2435
2436
        // Note getRegionCodeForCountryCode() is used because formatting information for regions which
2437
        // share a country calling code is contained by only one region for performance reasons. For
2438
        // example, for NANPA regions it will be contained in the metadata for US.
2439 2
        $regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
2440
        // Metadata cannot be null because the country calling code is valid.
2441 2
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode);
2442
2443 2
        $formattedNumber = $this->formatNsn(
2444 2
            $nationalSignificantNumber,
2445 2
            $metadata,
2446 2
            PhoneNumberFormat::NATIONAL,
2447
            $carrierCode
2448 2
        );
2449 2
        $this->maybeAppendFormattedExtension($number, $metadata, PhoneNumberFormat::NATIONAL, $formattedNumber);
2450 2
        $this->prefixNumberWithCountryCallingCode(
2451 2
            $countryCallingCode,
2452 2
            PhoneNumberFormat::NATIONAL,
2453
            $formattedNumber
2454 2
        );
2455 2
        return $formattedNumber;
2456
    }
2457
2458
    /**
2459
     * Formats a phone number in national format for dialing using the carrier as specified in the
2460
     * preferredDomesticCarrierCode field of the PhoneNumber object passed in. If that is missing,
2461
     * use the {@code fallbackCarrierCode} passed in instead. If there is no
2462
     * {@code preferredDomesticCarrierCode}, and the {@code fallbackCarrierCode} contains an empty
2463
     * string, return the number in national format without any carrier code.
2464
     *
2465
     * <p>Use {@link #formatNationalNumberWithCarrierCode} instead if the carrier code passed in
2466
     * should take precedence over the number's {@code preferredDomesticCarrierCode} when formatting.
2467
     *
2468
     * @param PhoneNumber $number the phone number to be formatted
2469
     * @param string $fallbackCarrierCode the carrier selection code to be used, if none is found in the
2470
     *     phone number itself
2471
     * @return string the formatted phone number in national format for dialing using the number's
2472
     *     {@code preferredDomesticCarrierCode}, or the {@code fallbackCarrierCode} passed in if
2473
     *     none is found
2474
     */
2475 1
    public function formatNationalNumberWithPreferredCarrierCode(PhoneNumber $number, $fallbackCarrierCode)
2476
    {
2477 1
        return $this->formatNationalNumberWithCarrierCode(
2478 1
            $number,
2479
            // Historically, we set this to an empty string when parsing with raw input if none was
2480
            // found in the input string. However, this doesn't result in a number we can dial. For this
2481
            // reason, we treat the empty string the same as if it isn't set at all.
2482 1
            mb_strlen($number->getPreferredDomesticCarrierCode()) > 0
2483 1
                ? $number->getPreferredDomesticCarrierCode()
2484 1
                : $fallbackCarrierCode
2485 1
        );
2486
    }
2487
2488
    /**
2489
     * Returns true if the number can be dialled from outside the region, or unknown. If the number
2490
     * can only be dialled from within the region, returns false. Does not check the number is a valid
2491
     * number. Note that, at the moment, this method does not handle short numbers (which are
2492
     * currently all presumed to not be diallable from outside their country).
2493
     *
2494
     * @param PhoneNumber $number the phone-number for which we want to know whether it is diallable from outside the region
2495
     * @return bool
2496
     */
2497 2
    public function canBeInternationallyDialled(PhoneNumber $number)
2498
    {
2499 2
        $metadata = $this->getMetadataForRegion($this->getRegionCodeForNumber($number));
2500 2
        if ($metadata === null) {
2501
            // Note numbers belonging to non-geographical entities (e.g. +800 numbers) are always
2502
            // internationally diallable, and will be caught here.
2503 2
            return true;
2504
        }
2505 2
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
2506 2
        return !$this->isNumberMatchingDesc($nationalSignificantNumber, $metadata->getNoInternationalDialling());
2507
    }
2508
2509
    /**
2510
     * Normalizes a string of characters representing a phone number. This strips all characters which
2511
     * are not diallable on a mobile phone keypad (including all non-ASCII digits).
2512
     *
2513
     * @param string $number a string of characters representing a phone number
2514
     * @return string the normalized string version of the phone number
2515
     */
2516 29
    public static function normalizeDiallableCharsOnly($number)
2517
    {
2518 29
        if (count(static::$DIALLABLE_CHAR_MAPPINGS) === 0) {
2519 1
            static::initDiallableCharMappings();
2520 1
        }
2521
2522 29
        return static::normalizeHelper($number, static::$DIALLABLE_CHAR_MAPPINGS, true /* remove non matches */);
2523
    }
2524
2525
    /**
2526
     * Formats a phone number for out-of-country dialing purposes.
2527
     *
2528
     * Note that in this version, if the number was entered originally using alpha characters and
2529
     * this version of the number is stored in raw_input, this representation of the number will be
2530
     * used rather than the digit representation. Grouping information, as specified by characters
2531
     * such as "-" and " ", will be retained.
2532
     *
2533
     * <p><b>Caveats:</b></p>
2534
     * <ul>
2535
     *  <li> This will not produce good results if the country calling code is both present in the raw
2536
     *       input _and_ is the start of the national number. This is not a problem in the regions
2537
     *       which typically use alpha numbers.
2538
     *  <li> This will also not produce good results if the raw input has any grouping information
2539
     *       within the first three digits of the national number, and if the function needs to strip
2540
     *       preceding digits/words in the raw input before these digits. Normally people group the
2541
     *       first three digits together so this is not a huge problem - and will be fixed if it
2542
     *       proves to be so.
2543
     * </ul>
2544
     *
2545
     * @param PhoneNumber $number the phone number that needs to be formatted
2546
     * @param String $regionCallingFrom the region where the call is being placed
2547
     * @return String the formatted phone number
2548
     */
2549 1
    public function formatOutOfCountryKeepingAlphaChars(PhoneNumber $number, $regionCallingFrom)
2550
    {
2551 1
        $rawInput = $number->getRawInput();
2552
        // If there is no raw input, then we can't keep alpha characters because there aren't any.
2553
        // In this case, we return formatOutOfCountryCallingNumber.
2554 1
        if (mb_strlen($rawInput) == 0) {
2555 1
            return $this->formatOutOfCountryCallingNumber($number, $regionCallingFrom);
2556
        }
2557 1
        $countryCode = $number->getCountryCode();
2558 1
        if (!$this->hasValidCountryCallingCode($countryCode)) {
2559 1
            return $rawInput;
2560
        }
2561
        // Strip any prefix such as country calling code, IDD, that was present. We do this by comparing
2562
        // the number in raw_input with the parsed number.
2563
        // To do this, first we normalize punctuation. We retain number grouping symbols such as " "
2564
        // only.
2565 1
        $rawInput = self::normalizeHelper($rawInput, static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS, true);
2566
        // Now we trim everything before the first three digits in the parsed number. We choose three
2567
        // because all valid alpha numbers have 3 digits at the start - if it does not, then we don't
2568
        // trim anything at all. Similarly, if the national number was less than three digits, we don't
2569
        // trim anything at all.
2570 1
        $nationalNumber = $this->getNationalSignificantNumber($number);
2571 1
        if (mb_strlen($nationalNumber) > 3) {
2572 1
            $firstNationalNumberDigit = strpos($rawInput, substr($nationalNumber, 0, 3));
2573 1
            if ($firstNationalNumberDigit !== false) {
2574 1
                $rawInput = substr($rawInput, $firstNationalNumberDigit);
2575 1
            }
2576 1
        }
2577 1
        $metadataForRegionCallingFrom = $this->getMetadataForRegion($regionCallingFrom);
2578 1
        if ($countryCode == static::NANPA_COUNTRY_CODE) {
2579 1
            if ($this->isNANPACountry($regionCallingFrom)) {
2580 1
                return $countryCode . ' ' . $rawInput;
2581
            }
2582 1
        } elseif ($metadataForRegionCallingFrom !== null &&
2583 1
            $countryCode == $this->getCountryCodeForValidRegion($regionCallingFrom)
2584 1
        ) {
2585
            $formattingPattern =
2586 1
                $this->chooseFormattingPatternForNumber(
2587 1
                    $metadataForRegionCallingFrom->numberFormats(),
2588
                    $nationalNumber
2589 1
                );
2590 1
            if ($formattingPattern === null) {
2591
                // If no pattern above is matched, we format the original input.
2592 1
                return $rawInput;
2593
            }
2594 1
            $newFormat = new NumberFormat();
2595 1
            $newFormat->mergeFrom($formattingPattern);
2596
            // The first group is the first group of digits that the user wrote together.
2597 1
            $newFormat->setPattern("(\\d+)(.*)");
2598
            // Here we just concatenate them back together after the national prefix has been fixed.
2599 1
            $newFormat->setFormat('$1$2');
2600
            // Now we format using this pattern instead of the default pattern, but with the national
2601
            // prefix prefixed if necessary.
2602
            // This will not work in the cases where the pattern (and not the leading digits) decide
2603
            // whether a national prefix needs to be used, since we have overridden the pattern to match
2604
            // anything, but that is not the case in the metadata to date.
2605 1
            return $this->formatNsnUsingPattern($rawInput, $newFormat, PhoneNumberFormat::NATIONAL);
2606
        }
2607 1
        $internationalPrefixForFormatting = '';
2608
        // If an unsupported region-calling-from is entered, or a country with multiple international
2609
        // prefixes, the international format of the number is returned, unless there is a preferred
2610
        // international prefix.
2611 1
        if ($metadataForRegionCallingFrom !== null) {
2612 1
            $internationalPrefix = $metadataForRegionCallingFrom->getInternationalPrefix();
2613 1
            $uniqueInternationalPrefixMatcher = new Matcher(static::SINGLE_INTERNATIONAL_PREFIX, $internationalPrefix);
2614
            $internationalPrefixForFormatting =
2615 1
                $uniqueInternationalPrefixMatcher->matches()
2616 1
                    ? $internationalPrefix
2617 1
                    : $metadataForRegionCallingFrom->getPreferredInternationalPrefix();
2618 1
        }
2619 1
        $formattedNumber = $rawInput;
2620 1
        $regionCode = $this->getRegionCodeForCountryCode($countryCode);
2621
        // Metadata cannot be null because the country calling code is valid.
2622 1
        $metadataForRegion = $this->getMetadataForRegionOrCallingCode($countryCode, $regionCode);
2623 1
        $this->maybeAppendFormattedExtension(
2624 1
            $number,
2625 1
            $metadataForRegion,
2626 1
            PhoneNumberFormat::INTERNATIONAL,
2627
            $formattedNumber
2628 1
        );
2629 1
        if (mb_strlen($internationalPrefixForFormatting) > 0) {
2630 1
            $formattedNumber = $internationalPrefixForFormatting . ' ' . $countryCode . ' ' . $formattedNumber;
2631 1
        } else {
2632
            // Invalid region entered as country-calling-from (so no metadata was found for it) or the
2633
            // region chosen has multiple international dialling prefixes.
2634 1
            $this->prefixNumberWithCountryCallingCode(
2635 1
                $countryCode,
2636 1
                PhoneNumberFormat::INTERNATIONAL,
2637
                $formattedNumber
2638 1
            );
2639
        }
2640 1
        return $formattedNumber;
2641
    }
2642
2643
    /**
2644
     * Formats a phone number for out-of-country dialing purposes. If no regionCallingFrom is
2645
     * supplied, we format the number in its INTERNATIONAL format. If the country calling code is the
2646
     * same as that of the region where the number is from, then NATIONAL formatting will be applied.
2647
     *
2648
     * <p>If the number itself has a country calling code of zero or an otherwise invalid country
2649
     * calling code, then we return the number with no formatting applied.
2650
     *
2651
     * <p>Note this function takes care of the case for calling inside of NANPA and between Russia and
2652
     * Kazakhstan (who share the same country calling code). In those cases, no international prefix
2653
     * is used. For regions which have multiple international prefixes, the number in its
2654
     * INTERNATIONAL format will be returned instead.
2655
     *
2656
     * @param PhoneNumber $number the phone number to be formatted
2657
     * @param string $regionCallingFrom the region where the call is being placed
2658
     * @return string  the formatted phone number
2659
     */
2660 8
    public function formatOutOfCountryCallingNumber(PhoneNumber $number, $regionCallingFrom)
2661
    {
2662 8
        if (!$this->isValidRegionCode($regionCallingFrom)) {
2663 1
            return $this->format($number, PhoneNumberFormat::INTERNATIONAL);
2664
        }
2665 7
        $countryCallingCode = $number->getCountryCode();
2666 7
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
2667 7
        if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
2668
            return $nationalSignificantNumber;
2669
        }
2670 7
        if ($countryCallingCode == static::NANPA_COUNTRY_CODE) {
2671 4
            if ($this->isNANPACountry($regionCallingFrom)) {
2672
                // For NANPA regions, return the national format for these regions but prefix it with the
2673
                // country calling code.
2674 1
                return $countryCallingCode . ' ' . $this->format($number, PhoneNumberFormat::NATIONAL);
2675
            }
2676 7
        } elseif ($countryCallingCode == $this->getCountryCodeForValidRegion($regionCallingFrom)) {
2677
            // If regions share a country calling code, the country calling code need not be dialled.
2678
            // This also applies when dialling within a region, so this if clause covers both these cases.
2679
            // Technically this is the case for dialling from La Reunion to other overseas departments of
2680
            // France (French Guiana, Martinique, Guadeloupe), but not vice versa - so we don't cover this
2681
            // edge case for now and for those cases return the version including country calling code.
2682
            // Details here: http://www.petitfute.com/voyage/225-info-pratiques-reunion
2683 2
            return $this->format($number, PhoneNumberFormat::NATIONAL);
2684
        }
2685
        // Metadata cannot be null because we checked 'isValidRegionCode()' above.
2686 7
        $metadataForRegionCallingFrom = $this->getMetadataForRegion($regionCallingFrom);
2687
2688 7
        $internationalPrefix = $metadataForRegionCallingFrom->getInternationalPrefix();
2689
2690
        // For regions that have multiple international prefixes, the international format of the
2691
        // number is returned, unless there is a preferred international prefix.
2692 7
        $internationalPrefixForFormatting = '';
2693 7
        $uniqueInternationalPrefixMatcher = new Matcher(static::SINGLE_INTERNATIONAL_PREFIX, $internationalPrefix);
2694
2695 7
        if ($uniqueInternationalPrefixMatcher->matches()) {
2696 6
            $internationalPrefixForFormatting = $internationalPrefix;
2697 7
        } elseif ($metadataForRegionCallingFrom->hasPreferredInternationalPrefix()) {
2698 3
            $internationalPrefixForFormatting = $metadataForRegionCallingFrom->getPreferredInternationalPrefix();
2699 3
        }
2700
2701 7
        $regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
2702
        // Metadata cannot be null because the country calling code is valid.
2703 7
        $metadataForRegion = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode);
2704 7
        $formattedNationalNumber = $this->formatNsn(
2705 7
            $nationalSignificantNumber,
2706 7
            $metadataForRegion,
2707
            PhoneNumberFormat::INTERNATIONAL
2708 7
        );
2709 7
        $formattedNumber = $formattedNationalNumber;
2710 7
        $this->maybeAppendFormattedExtension(
2711 7
            $number,
2712 7
            $metadataForRegion,
2713 7
            PhoneNumberFormat::INTERNATIONAL,
2714
            $formattedNumber
2715 7
        );
2716 7
        if (mb_strlen($internationalPrefixForFormatting) > 0) {
2717 7
            $formattedNumber = $internationalPrefixForFormatting . ' ' . $countryCallingCode . ' ' . $formattedNumber;
2718 7
        } else {
2719 1
            $this->prefixNumberWithCountryCallingCode(
2720 1
                $countryCallingCode,
2721 1
                PhoneNumberFormat::INTERNATIONAL,
2722
                $formattedNumber
2723 1
            );
2724
        }
2725 7
        return $formattedNumber;
2726
    }
2727
2728
    /**
2729
     * Checks if this is a region under the North American Numbering Plan Administration (NANPA).
2730
     * @param string $regionCode
2731
     * @return boolean true if regionCode is one of the regions under NANPA
2732
     */
2733 5
    public function isNANPACountry($regionCode)
2734
    {
2735 5
        return in_array($regionCode, $this->nanpaRegions);
2736
    }
2737
2738
    /**
2739
     * Formats a phone number using the original phone number format that the number is parsed from.
2740
     * The original format is embedded in the country_code_source field of the PhoneNumber object
2741
     * passed in. If such information is missing, the number will be formatted into the NATIONAL
2742
     * format by default. When we don't have a formatting pattern for the number, the method returns
2743
     * the raw inptu when it is available.
2744
     *
2745
     * Note this method guarantees no digit will be inserted, removed or modified as a result of
2746
     * formatting.
2747
     *
2748
     * @param PhoneNumber $number the phone number that needs to be formatted in its original number format
2749
     * @param string $regionCallingFrom the region whose IDD needs to be prefixed if the original number
2750
     *     has one
2751
     * @return string the formatted phone number in its original number format
2752
     */
2753 1
    public function formatInOriginalFormat(PhoneNumber $number, $regionCallingFrom)
2754
    {
2755 1
        if ($number->hasRawInput() && !$this->hasFormattingPatternForNumber($number)) {
2756
            // We check if we have the formatting pattern because without that, we might format the number
2757
            // as a group without national prefix.
2758 1
            return $number->getRawInput();
2759
        }
2760 1
        if (!$number->hasCountryCodeSource()) {
2761 1
            return $this->format($number, PhoneNumberFormat::NATIONAL);
2762
        }
2763 1
        switch ($number->getCountryCodeSource()) {
2764 1
            case CountryCodeSource::FROM_NUMBER_WITH_PLUS_SIGN:
2765 1
                $formattedNumber = $this->format($number, PhoneNumberFormat::INTERNATIONAL);
2766 1
                break;
2767 1
            case CountryCodeSource::FROM_NUMBER_WITH_IDD:
2768 1
                $formattedNumber = $this->formatOutOfCountryCallingNumber($number, $regionCallingFrom);
2769 1
                break;
2770 1
            case CountryCodeSource::FROM_NUMBER_WITHOUT_PLUS_SIGN:
2771 1
                $formattedNumber = substr($this->format($number, PhoneNumberFormat::INTERNATIONAL), 1);
2772 1
                break;
2773 1
            case CountryCodeSource::FROM_DEFAULT_COUNTRY:
2774
                // Fall-through to default case.
2775 1
            default:
2776
2777 1
                $regionCode = $this->getRegionCodeForCountryCode($number->getCountryCode());
2778
                // We strip non-digits from the NDD here, and from the raw input later, so that we can
2779
                // compare them easily.
2780 1
                $nationalPrefix = $this->getNddPrefixForRegion($regionCode, true /* strip non-digits */);
2781 1
                $nationalFormat = $this->format($number, PhoneNumberFormat::NATIONAL);
2782 1
                if ($nationalPrefix === null || mb_strlen($nationalPrefix) == 0) {
2783
                    // If the region doesn't have a national prefix at all, we can safely return the national
2784
                    // format without worrying about a national prefix being added.
2785 1
                    $formattedNumber = $nationalFormat;
2786 1
                    break;
2787
                }
2788
                // Otherwise, we check if the original number was entered with a national prefix.
2789 1
                if ($this->rawInputContainsNationalPrefix(
2790 1
                    $number->getRawInput(),
2791 1
                    $nationalPrefix,
2792
                    $regionCode
2793 1
                )
2794 1
                ) {
2795
                    // If so, we can safely return the national format.
2796 1
                    $formattedNumber = $nationalFormat;
2797 1
                    break;
2798
                }
2799
                // Metadata cannot be null here because getNddPrefixForRegion() (above) returns null if
2800
                // there is no metadata for the region.
2801 1
                $metadata = $this->getMetadataForRegion($regionCode);
2802 1
                $nationalNumber = $this->getNationalSignificantNumber($number);
2803 1
                $formatRule = $this->chooseFormattingPatternForNumber($metadata->numberFormats(), $nationalNumber);
2804
                // The format rule could still be null here if the national number was 0 and there was no
2805
                // raw input (this should not be possible for numbers generated by the phonenumber library
2806
                // as they would also not have a country calling code and we would have exited earlier).
2807 1
                if ($formatRule === null) {
2808
                    $formattedNumber = $nationalFormat;
2809
                    break;
2810
                }
2811
                // When the format we apply to this number doesn't contain national prefix, we can just
2812
                // return the national format.
2813
                // TODO: Refactor the code below with the code in isNationalPrefixPresentIfRequired.
2814 1
                $candidateNationalPrefixRule = $formatRule->getNationalPrefixFormattingRule();
2815
                // We assume that the first-group symbol will never be _before_ the national prefix.
2816 1
                $indexOfFirstGroup = strpos($candidateNationalPrefixRule, '$1');
2817 1
                if ($indexOfFirstGroup <= 0) {
2818 1
                    $formattedNumber = $nationalFormat;
2819 1
                    break;
2820
                }
2821 1
                $candidateNationalPrefixRule = substr($candidateNationalPrefixRule, 0, $indexOfFirstGroup);
2822 1
                $candidateNationalPrefixRule = static::normalizeDigitsOnly($candidateNationalPrefixRule);
2823 1
                if (mb_strlen($candidateNationalPrefixRule) == 0) {
2824
                    // National prefix not used when formatting this number.
2825
                    $formattedNumber = $nationalFormat;
2826
                    break;
2827
                }
2828
                // Otherwise, we need to remove the national prefix from our output.
2829 1
                $numFormatCopy = new NumberFormat();
2830 1
                $numFormatCopy->mergeFrom($formatRule);
2831 1
                $numFormatCopy->clearNationalPrefixFormattingRule();
2832 1
                $numberFormats = array();
2833 1
                $numberFormats[] = $numFormatCopy;
2834 1
                $formattedNumber = $this->formatByPattern($number, PhoneNumberFormat::NATIONAL, $numberFormats);
2835 1
                break;
2836 1
        }
2837 1
        $rawInput = $number->getRawInput();
2838
        // If no digit is inserted/removed/modified as a result of our formatting, we return the
2839
        // formatted phone number; otherwise we return the raw input the user entered.
2840 1
        if ($formattedNumber !== null && mb_strlen($rawInput) > 0) {
2841 1
            $normalizedFormattedNumber = static::normalizeDiallableCharsOnly($formattedNumber);
2842 1
            $normalizedRawInput = static::normalizeDiallableCharsOnly($rawInput);
2843 1
            if ($normalizedFormattedNumber != $normalizedRawInput) {
2844 1
                $formattedNumber = $rawInput;
2845 1
            }
2846 1
        }
2847 1
        return $formattedNumber;
2848
    }
2849
2850
    /**
2851
     * @param PhoneNumber $number
2852
     * @return bool
2853
     */
2854 1
    protected function hasFormattingPatternForNumber(PhoneNumber $number)
2855
    {
2856 1
        $countryCallingCode = $number->getCountryCode();
2857 1
        $phoneNumberRegion = $this->getRegionCodeForCountryCode($countryCallingCode);
2858 1
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $phoneNumberRegion);
2859 1
        if ($metadata === null) {
2860
            return false;
2861
        }
2862 1
        $nationalNumber = $this->getNationalSignificantNumber($number);
2863 1
        $formatRule = $this->chooseFormattingPatternForNumber($metadata->numberFormats(), $nationalNumber);
2864 1
        return $formatRule !== null;
2865
    }
2866
2867
    /**
2868
     * Returns the national dialling prefix for a specific region. For example, this would be 1 for
2869
     * the United States, and 0 for New Zealand. Set stripNonDigits to true to strip symbols like "~"
2870
     * (which indicates a wait for a dialling tone) from the prefix returned. If no national prefix is
2871
     * present, we return null.
2872
     *
2873
     * <p>Warning: Do not use this method for do-your-own formatting - for some regions, the
2874
     * national dialling prefix is used only for certain types of numbers. Use the library's
2875
     * formatting functions to prefix the national prefix when required.
2876
     *
2877
     * @param string $regionCode the region that we want to get the dialling prefix for
2878
     * @param boolean $stripNonDigits true to strip non-digits from the national dialling prefix
2879
     * @return string the dialling prefix for the region denoted by regionCode
2880
     */
2881 28
    public function getNddPrefixForRegion($regionCode, $stripNonDigits)
2882
    {
2883 28
        $metadata = $this->getMetadataForRegion($regionCode);
2884 28
        if ($metadata === null) {
2885 1
            return null;
2886
        }
2887 28
        $nationalPrefix = $metadata->getNationalPrefix();
2888
        // If no national prefix was found, we return null.
2889 28
        if (mb_strlen($nationalPrefix) == 0) {
2890 1
            return null;
2891
        }
2892 28
        if ($stripNonDigits) {
2893
            // Note: if any other non-numeric symbols are ever used in national prefixes, these would have
2894
            // to be removed here as well.
2895 28
            $nationalPrefix = str_replace('~', '', $nationalPrefix);
2896 28
        }
2897 28
        return $nationalPrefix;
2898
    }
2899
2900
    /**
2901
     * Check if rawInput, which is assumed to be in the national format, has a national prefix. The
2902
     * national prefix is assumed to be in digits-only form.
2903
     * @param string $rawInput
2904
     * @param string $nationalPrefix
2905
     * @param string $regionCode
2906
     * @return bool
2907
     */
2908 1
    protected function rawInputContainsNationalPrefix($rawInput, $nationalPrefix, $regionCode)
2909
    {
2910 1
        $normalizedNationalNumber = static::normalizeDigitsOnly($rawInput);
2911 1
        if (strpos($normalizedNationalNumber, $nationalPrefix) === 0) {
2912
            try {
2913
                // Some Japanese numbers (e.g. 00777123) might be mistaken to contain the national prefix
2914
                // when written without it (e.g. 0777123) if we just do prefix matching. To tackle that, we
2915
                // check the validity of the number if the assumed national prefix is removed (777123 won't
2916
                // be valid in Japan).
2917 1
                return $this->isValidNumber(
2918 1
                    $this->parse(substr($normalizedNationalNumber, mb_strlen($nationalPrefix)), $regionCode)
2919 1
                );
2920
            } catch (NumberParseException $e) {
2921
                return false;
2922
            }
2923
        }
2924 1
        return false;
2925
    }
2926
2927
    /**
2928
     * Tests whether a phone number matches a valid pattern. Note this doesn't verify the number
2929
     * is actually in use, which is impossible to tell by just looking at a number itself. It only
2930
     * verifies whether the parsed, canonicalised number is valid: not whether a particular series of
2931
     * digits entered by the user is diallable from the region provided when parsing. For example, the
2932
     * number +41 (0) 78 927 2696 can be parsed into a number with country code "41" and national
2933
     * significant number "789272696". This is valid, while the original string is not diallable.
2934
     *
2935
     * @param PhoneNumber $number the phone number that we want to validate
2936
     * @return boolean that indicates whether the number is of a valid pattern
2937
     */
2938 2006
    public function isValidNumber(PhoneNumber $number)
2939
    {
2940 2006
        $regionCode = $this->getRegionCodeForNumber($number);
2941 2006
        return $this->isValidNumberForRegion($number, $regionCode);
2942
    }
2943
2944
    /**
2945
     * Tests whether a phone number is valid for a certain region. Note this doesn't verify the number
2946
     * is actually in use, which is impossible to tell by just looking at a number itself. If the
2947
     * country calling code is not the same as the country calling code for the region, this
2948
     * immediately exits with false. After this, the specific number pattern rules for the region are
2949
     * examined. This is useful for determining for example whether a particular number is valid for
2950
     * Canada, rather than just a valid NANPA number.
2951
     * Warning: In most cases, you want to use {@link #isValidNumber} instead. For example, this
2952
     * method will mark numbers from British Crown dependencies such as the Isle of Man as invalid for
2953
     * the region "GB" (United Kingdom), since it has its own region code, "IM", which may be
2954
     * undesirable.
2955
     *
2956
     * @param PhoneNumber $number the phone number that we want to validate
2957
     * @param string $regionCode the region that we want to validate the phone number for
2958
     * @return boolean that indicates whether the number is of a valid pattern
2959
     */
2960 2012
    public function isValidNumberForRegion(PhoneNumber $number, $regionCode)
2961
    {
2962 2012
        $countryCode = $number->getCountryCode();
2963 2012
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCode, $regionCode);
2964 2012
        if (($metadata === null) ||
2965 1962
            (static::REGION_CODE_FOR_NON_GEO_ENTITY !== $regionCode &&
2966 1953
                $countryCode !== $this->getCountryCodeForValidRegion($regionCode))
2967 2012
        ) {
2968
            // Either the region code was invalid, or the country calling code for this number does not
2969
            // match that of the region code.
2970 64
            return false;
2971
        }
2972 1961
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
2973
2974 1961
        return $this->getNumberTypeHelper($nationalSignificantNumber, $metadata) != PhoneNumberType::UNKNOWN;
2975
    }
2976
2977
    /**
2978
     * Parses a string and returns it as a phone number in proto buffer format. The method is quite
2979
     * lenient and looks for a number in the input text (raw input) and does not check whether the
2980
     * string is definitely only a phone number. To do this, it ignores punctuation and white-space,
2981
     * as well as any text before the number (e.g. a leading “Tel: ”) and trims the non-number bits.
2982
     * It will accept a number in any format (E164, national, international etc), assuming it can
2983
     * interpreted with the defaultRegion supplied. It also attempts to convert any alpha characters
2984
     * into digits if it thinks this is a vanity number of the type "1800 MICROSOFT".
2985
     *
2986
     * <p> This method will throw a {@link NumberParseException} if the number is not considered to
2987
     * be a possible number. Note that validation of whether the number is actually a valid number
2988
     * for a particular region is not performed. This can be done separately with {@link #isValidNumber}.
2989
     *
2990
     * <p> Note this method canonicalizes the phone number such that different representations can be
2991
     * easily compared, no matter what form it was originally entered in (e.g. national,
2992
     * international). If you want to record context about the number being parsed, such as the raw
2993
     * input that was entered, how the country code was derived etc. then call {@link
2994
     * #parseAndKeepRawInput} instead.
2995
     *
2996
     * @param string $numberToParse number that we are attempting to parse. This can contain formatting
2997
     *                          such as +, ( and -, as well as a phone number extension.
2998
     * @param string|null $defaultRegion region that we are expecting the number to be from. This is only used
2999
     *                          if the number being parsed is not written in international format.
3000
     *                          The country_code for the number in this case would be stored as that
3001
     *                          of the default region supplied. If the number is guaranteed to
3002
     *                          start with a '+' followed by the country calling code, then
3003
     *                          "ZZ" or null can be supplied.
3004
     * @param PhoneNumber|null $phoneNumber
3005
     * @param bool $keepRawInput
3006
     * @return PhoneNumber a phone number proto buffer filled with the parsed number
3007
     * @throws NumberParseException  if the string is not considered to be a viable phone number (e.g.
3008
     *                               too few or too many digits) or if no default region was supplied
3009
     *                               and the number is not in international format (does not start
3010
     *                               with +)
3011
     */
3012 3102
    public function parse($numberToParse, $defaultRegion = null, PhoneNumber $phoneNumber = null, $keepRawInput = false)
3013
    {
3014 3102
        if ($phoneNumber === null) {
3015 3102
            $phoneNumber = new PhoneNumber();
3016 3102
        }
3017 3102
        $this->parseHelper($numberToParse, $defaultRegion, $keepRawInput, true, $phoneNumber);
3018 3097
        return $phoneNumber;
3019
    }
3020
3021
    /**
3022
     * Formats a phone number in the specified format using client-defined formatting rules. Note that
3023
     * if the phone number has a country calling code of zero or an otherwise invalid country calling
3024
     * code, we cannot work out things like whether there should be a national prefix applied, or how
3025
     * to format extensions, so we return the national significant number with no formatting applied.
3026
     *
3027
     * @param PhoneNumber $number the phone number to be formatted
3028
     * @param int $numberFormat the format the phone number should be formatted into
3029
     * @param array $userDefinedFormats formatting rules specified by clients
3030
     * @return String the formatted phone number
3031
     */
3032 2
    public function formatByPattern(PhoneNumber $number, $numberFormat, array $userDefinedFormats)
3033
    {
3034 2
        $countryCallingCode = $number->getCountryCode();
3035 2
        $nationalSignificantNumber = $this->getNationalSignificantNumber($number);
3036 2
        if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
3037
            return $nationalSignificantNumber;
3038
        }
3039
        // Note getRegionCodeForCountryCode() is used because formatting information for regions which
3040
        // share a country calling code is contained by only one region for performance reasons. For
3041
        // example, for NANPA regions it will be contained in the metadata for US.
3042 2
        $regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
3043
        // Metadata cannot be null because the country calling code is valid
3044 2
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode);
3045
3046 2
        $formattedNumber = '';
3047
3048 2
        $formattingPattern = $this->chooseFormattingPatternForNumber($userDefinedFormats, $nationalSignificantNumber);
3049 2
        if ($formattingPattern === null) {
3050
            // If no pattern above is matched, we format the number as a whole.
3051
            $formattedNumber .= $nationalSignificantNumber;
3052
        } else {
3053 2
            $numFormatCopy = new NumberFormat();
3054
            // Before we do a replacement of the national prefix pattern $NP with the national prefix, we
3055
            // need to copy the rule so that subsequent replacements for different numbers have the
3056
            // appropriate national prefix.
3057 2
            $numFormatCopy->mergeFrom($formattingPattern);
3058 2
            $nationalPrefixFormattingRule = $formattingPattern->getNationalPrefixFormattingRule();
3059 2
            if (mb_strlen($nationalPrefixFormattingRule) > 0) {
3060 1
                $nationalPrefix = $metadata->getNationalPrefix();
3061 1
                if (mb_strlen($nationalPrefix) > 0) {
3062
                    // Replace $NP with national prefix and $FG with the first group ($1).
3063 1
                    $nationalPrefixFormattingRule = str_replace(array(static::NP_STRING, static::FG_STRING),
3064 1
                        array($nationalPrefix, '$1'), $nationalPrefixFormattingRule);
3065 1
                    $numFormatCopy->setNationalPrefixFormattingRule($nationalPrefixFormattingRule);
3066 1
                } else {
3067
                    // We don't want to have a rule for how to format the national prefix if there isn't one.
3068 1
                    $numFormatCopy->clearNationalPrefixFormattingRule();
3069
                }
3070 1
            }
3071 2
            $formattedNumber .= $this->formatNsnUsingPattern($nationalSignificantNumber, $numFormatCopy, $numberFormat);
3072
        }
3073 2
        $this->maybeAppendFormattedExtension($number, $metadata, $numberFormat, $formattedNumber);
3074 2
        $this->prefixNumberWithCountryCallingCode($countryCallingCode, $numberFormat, $formattedNumber);
3075 2
        return $formattedNumber;
3076
    }
3077
3078
    /**
3079
     * Gets a valid number for the specified region.
3080
     *
3081
     * @param string regionCode  the region for which an example number is needed
0 ignored issues
show
Bug introduced by
The type libphonenumber\regionCode was not found. Maybe you did not declare it correctly or list all dependencies?

The issue could also be caused by a filter entry in the build configuration. If the path has been excluded in your configuration, e.g. excluded_paths: ["lib/*"], you can move it to the dependency path list as follows:

filter:
    dependency_paths: ["lib/*"]

For further information see https://scrutinizer-ci.com/docs/tools/php/php-scrutinizer/#list-dependency-paths

Loading history...
3082
     * @return PhoneNumber a valid fixed-line number for the specified region. Returns null when the metadata
3083
     *    does not contain such information, or the region 001 is passed in. For 001 (representing
3084
     *    non-geographical numbers), call {@link #getExampleNumberForNonGeoEntity} instead.
3085
     */
3086 248
    public function getExampleNumber($regionCode)
3087
    {
3088 248
        return $this->getExampleNumberForType($regionCode, PhoneNumberType::FIXED_LINE);
3089
    }
3090
3091
    /**
3092
     * Gets an invalid number for the specified region. This is useful for unit-testing purposes,
3093
     * where you want to test what will happen with an invalid number. Note that the number that is
3094
     * returned will always be able to be parsed and will have the correct country code. It may also
3095
     * be a valid *short* number/code for this region. Validity checking such numbers is handled with
3096
     * {@link ShortNumberInfo}.
3097
     *
3098
     * @param string $regionCode The region for which an example number is needed
3099
     * @return PhoneNumber|null An invalid number for the specified region. Returns null when an unsupported region
3100
     * or the region 001 (Earth) is passed in.
3101
     */
3102 245
    public function getInvalidExampleNumber($regionCode)
3103
    {
3104 245
        if (!$this->isValidRegionCode($regionCode)) {
3105
            return null;
3106
        }
3107
3108
        // We start off with a valid fixed-line number since every country supports this. Alternatively
3109
        // we could start with a different number type, since fixed-line numbers typically have a wide
3110
        // breadth of valid number lengths and we may have to make it very short before we get an
3111
        // invalid number.
3112
3113 245
        $desc = $this->getNumberDescByType($this->getMetadataForRegion($regionCode), PhoneNumberType::FIXED_LINE);
3114
3115 245
        if ($desc->getExampleNumber() == '') {
3116
            // This shouldn't happen; we have a test for this.
3117
            return null;
3118
        }
3119
3120 245
        $exampleNumber = $desc->getExampleNumber();
3121
3122
        // Try and make the number invalid. We do this by changing the length. We try reducing the
3123
        // length of the number, since currently no region has a number that is the same length as
3124
        // MIN_LENGTH_FOR_NSN. This is probably quicker than making the number longer, which is another
3125
        // alternative. We could also use the possible number pattern to extract the possible lengths of
3126
        // the number to make this faster, but this method is only for unit-testing so simplicity is
3127
        // preferred to performance.  We don't want to return a number that can't be parsed, so we check
3128
        // the number is long enough. We try all possible lengths because phone number plans often have
3129
        // overlapping prefixes so the number 123456 might be valid as a fixed-line number, and 12345 as
3130
        // a mobile number. It would be faster to loop in a different order, but we prefer numbers that
3131
        // look closer to real numbers (and it gives us a variety of different lengths for the resulting
3132
        // phone numbers - otherwise they would all be MIN_LENGTH_FOR_NSN digits long.)
3133 245
        for ($phoneNumberLength = mb_strlen($exampleNumber) - 1; $phoneNumberLength >= static::MIN_LENGTH_FOR_NSN; $phoneNumberLength--) {
3134 245
            $numberToTry = mb_substr($exampleNumber, 0, $phoneNumberLength);
3135
            try {
3136 245
                $possiblyValidNumber = $this->parse($numberToTry, $regionCode);
3137 245
                if (!$this->isValidNumber($possiblyValidNumber)) {
3138 245
                    return $possiblyValidNumber;
3139
                }
3140 16
            } catch (NumberParseException $e) {
3141
                // Shouldn't happen: we have already checked the length, we know example numbers have
3142
                // only valid digits, and we know the region code is fine.
3143
            }
3144 16
        }
3145
        // We have a test to check that this doesn't happen for any of our supported regions.
3146
        return null;
3147
    }
3148
3149
    /**
3150
     * Gets a valid number for the specified region and number type.
3151
     *
3152
     * @param string|int $regionCodeOrType the region for which an example number is needed
3153
     * @param int $type the PhoneNumberType of number that is needed
3154
     * @return PhoneNumber a valid number for the specified region and type. Returns null when the metadata
3155
     *     does not contain such information or if an invalid region or region 001 was entered.
3156
     *     For 001 (representing non-geographical numbers), call
3157
     *     {@link #getExampleNumberForNonGeoEntity} instead.
3158
     *
3159
     * If $regionCodeOrType is the only parameter supplied, then a valid number for the specified number type
3160
     * will be returned that may belong to any country.
3161
     */
3162 3188
    public function getExampleNumberForType($regionCodeOrType, $type = null)
3163
    {
3164 3188
        if ($regionCodeOrType !== null && $type === null) {
3165
            /*
3166
             * Gets a valid number for the specified number type (it may belong to any country).
3167
             */
3168 12
            foreach ($this->getSupportedRegions() as $regionCode) {
3169 12
                $exampleNumber = $this->getExampleNumberForType($regionCode, $regionCodeOrType);
3170 12
                if ($exampleNumber !== null) {
3171 12
                    return $exampleNumber;
3172
                }
3173 4
            }
3174
3175
            // If there wasn't an example number for a region, try the non-geographical entities
3176
            foreach ($this->getSupportedGlobalNetworkCallingCodes() as $countryCallingCode) {
3177
                $desc = $this->getNumberDescByType($this->getMetadataForNonGeographicalRegion($countryCallingCode), $regionCodeOrType);
3178
                try {
3179
                    if ($desc->getExampleNumber() != '') {
3180
                        return $this->parse('+' . $countryCallingCode . $desc->getExampleNumber(), static::UNKNOWN_REGION);
3181
                    }
3182
                } catch (NumberParseException $e) {
3183
                    // noop
3184
                }
3185
            }
3186
            // There are no example numbers of this type for any country in the library.
3187
            return null;
3188
        }
3189
3190
        // Check the region code is valid.
3191 3188
        if (!$this->isValidRegionCode($regionCodeOrType)) {
3192 1
            return null;
3193
        }
3194 3188
        $desc = $this->getNumberDescByType($this->getMetadataForRegion($regionCodeOrType), $type);
3195
        try {
3196 3188
            if ($desc->hasExampleNumber()) {
3197 1834
                return $this->parse($desc->getExampleNumber(), $regionCodeOrType);
3198
            }
3199 1359
        } catch (NumberParseException $e) {
3200
            // noop
3201
        }
3202 1359
        return null;
3203
    }
3204
3205
    /**
3206
     * @param PhoneMetadata $metadata
3207
     * @param int $type PhoneNumberType
3208
     * @return PhoneNumberDesc
3209
     */
3210 4632
    protected function getNumberDescByType(PhoneMetadata $metadata, $type)
3211
    {
3212
        switch ($type) {
3213 4632
            case PhoneNumberType::PREMIUM_RATE:
3214 251
                return $metadata->getPremiumRate();
3215 4530
            case PhoneNumberType::TOLL_FREE:
3216 251
                return $metadata->getTollFree();
3217 4454
            case PhoneNumberType::MOBILE:
3218 257
                return $metadata->getMobile();
3219 4453
            case PhoneNumberType::FIXED_LINE:
3220 4453
            case PhoneNumberType::FIXED_LINE_OR_MOBILE:
3221 1230
                return $metadata->getFixedLine();
3222 4450
            case PhoneNumberType::SHARED_COST:
3223 248
                return $metadata->getSharedCost();
3224 4258
            case PhoneNumberType::VOIP:
3225 248
                return $metadata->getVoip();
3226 4100
            case PhoneNumberType::PERSONAL_NUMBER:
3227 248
                return $metadata->getPersonalNumber();
3228 3914
            case PhoneNumberType::PAGER:
3229 248
                return $metadata->getPager();
3230 3690
            case PhoneNumberType::UAN:
3231 248
                return $metadata->getUan();
3232 3505
            case PhoneNumberType::VOICEMAIL:
3233 249
                return $metadata->getVoicemail();
3234 3275
            default:
3235 3275
                return $metadata->getGeneralDesc();
3236 3275
        }
3237
    }
3238
3239
    /**
3240
     * Gets a valid number for the specified country calling code for a non-geographical entity.
3241
     *
3242
     * @param int $countryCallingCode the country calling code for a non-geographical entity
3243
     * @return PhoneNumber a valid number for the non-geographical entity. Returns null when the metadata
3244
     *    does not contain such information, or the country calling code passed in does not belong
3245
     *    to a non-geographical entity.
3246
     */
3247 10
    public function getExampleNumberForNonGeoEntity($countryCallingCode)
3248
    {
3249 10
        $metadata = $this->getMetadataForNonGeographicalRegion($countryCallingCode);
3250 10
        if ($metadata !== null) {
3251
            // For geographical entities, fixed-line data is always present. However, for non-geographical
3252
            // entities, this is not the case, so we have to go through different types to find the
3253
            // example number. We don't check fixed-line or personal number since they aren't used by
3254
            // non-geographical entities (if this changes, a unit-test will catch this.)
3255
            /** @var PhoneNumberDesc[] $list */
3256
            $list = array(
3257 10
                $metadata->getMobile(),
3258 10
                $metadata->getTollFree(),
3259 10
                $metadata->getSharedCost(),
3260 10
                $metadata->getVoip(),
3261 10
                $metadata->getVoicemail(),
3262 10
                $metadata->getUan(),
3263 10
                $metadata->getPremiumRate(),
3264 10
            );
3265 10
            foreach ($list as $desc) {
3266
                try {
3267 10
                    if ($desc !== null && $desc->hasExampleNumber()) {
3268 10
                        return $this->parse('+' . $countryCallingCode . $desc->getExampleNumber(), self::UNKNOWN_REGION);
3269
                    }
3270 7
                } catch (NumberParseException $e) {
3271
                    // noop
3272
                }
3273 7
            }
3274
        }
3275
        return null;
3276
    }
3277
3278
3279
    /**
3280
     * Takes two phone numbers and compares them for equality.
3281
     *
3282
     * <p>Returns EXACT_MATCH if the country_code, NSN, presence of a leading zero
3283
     * for Italian numbers and any extension present are the same. Returns NSN_MATCH
3284
     * if either or both has no region specified, and the NSNs and extensions are
3285
     * the same. Returns SHORT_NSN_MATCH if either or both has no region specified,
3286
     * or the region specified is the same, and one NSN could be a shorter version
3287
     * of the other number. This includes the case where one has an extension
3288
     * specified, and the other does not. Returns NO_MATCH otherwise. For example,
3289
     * the numbers +1 345 657 1234 and 657 1234 are a SHORT_NSN_MATCH. The numbers
3290
     * +1 345 657 1234 and 345 657 are a NO_MATCH.
3291
     *
3292
     * @param $firstNumberIn PhoneNumber|string First number to compare. If it is a
3293
     * string it can contain formatting, and can have country calling code specified
3294
     * with + at the start.
3295
     * @param $secondNumberIn PhoneNumber|string Second 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
     * @throws \InvalidArgumentException
3299
     * @return int {MatchType} NOT_A_NUMBER, NO_MATCH,
3300
     */
3301 8
    public function isNumberMatch($firstNumberIn, $secondNumberIn)
3302
    {
3303 8
        if (is_string($firstNumberIn) && is_string($secondNumberIn)) {
3304
            try {
3305 4
                $firstNumberAsProto = $this->parse($firstNumberIn, static::UNKNOWN_REGION);
3306 4
                return $this->isNumberMatch($firstNumberAsProto, $secondNumberIn);
3307 3
            } catch (NumberParseException $e) {
3308 3
                if ($e->getErrorType() === NumberParseException::INVALID_COUNTRY_CODE) {
3309
                    try {
3310 3
                        $secondNumberAsProto = $this->parse($secondNumberIn, static::UNKNOWN_REGION);
3311 2
                        return $this->isNumberMatch($secondNumberAsProto, $firstNumberIn);
3312 3
                    } catch (NumberParseException $e2) {
3313 3
                        if ($e2->getErrorType() === NumberParseException::INVALID_COUNTRY_CODE) {
3314
                            try {
3315 3
                                $firstNumberProto = new PhoneNumber();
3316 3
                                $secondNumberProto = new PhoneNumber();
3317 3
                                $this->parseHelper($firstNumberIn, null, false, false, $firstNumberProto);
3318 3
                                $this->parseHelper($secondNumberIn, null, false, false, $secondNumberProto);
3319 3
                                return $this->isNumberMatch($firstNumberProto, $secondNumberProto);
3320
                            } catch (NumberParseException $e3) {
3321
                                // Fall through and return MatchType::NOT_A_NUMBER
3322
                            }
3323
                        }
3324
                    }
3325
                }
3326
            }
3327 1
            return MatchType::NOT_A_NUMBER;
3328
        }
3329 8
        if ($firstNumberIn instanceof PhoneNumber && is_string($secondNumberIn)) {
3330
            // First see if the second number has an implicit country calling code, by attempting to parse
3331
            // it.
3332
            try {
3333 4
                $secondNumberAsProto = $this->parse($secondNumberIn, static::UNKNOWN_REGION);
3334 2
                return $this->isNumberMatch($firstNumberIn, $secondNumberAsProto);
3335 3
            } catch (NumberParseException $e) {
3336 3
                if ($e->getErrorType() === NumberParseException::INVALID_COUNTRY_CODE) {
3337
                    // The second number has no country calling code. EXACT_MATCH is no longer possible.
3338
                    // We parse it as if the region was the same as that for the first number, and if
3339
                    // EXACT_MATCH is returned, we replace this with NSN_MATCH.
3340 3
                    $firstNumberRegion = $this->getRegionCodeForCountryCode($firstNumberIn->getCountryCode());
3341
                    try {
3342 3
                        if ($firstNumberRegion != static::UNKNOWN_REGION) {
3343 3
                            $secondNumberWithFirstNumberRegion = $this->parse($secondNumberIn, $firstNumberRegion);
3344 3
                            $match = $this->isNumberMatch($firstNumberIn, $secondNumberWithFirstNumberRegion);
3345 3
                            if ($match === MatchType::EXACT_MATCH) {
3346 1
                                return MatchType::NSN_MATCH;
3347
                            }
3348 2
                            return $match;
3349
                        }
3350
3351
                        // If the first number didn't have a valid country calling code, then we parse the
3352
                        // second number without one as well.
3353 1
                        $secondNumberProto = new PhoneNumber();
3354 1
                        $this->parseHelper($secondNumberIn, null, false, false, $secondNumberProto);
3355 1
                        return $this->isNumberMatch($firstNumberIn, $secondNumberProto);
3356
                    } catch (NumberParseException $e2) {
3357
                        // Fall-through to return NOT_A_NUMBER.
3358
                    }
3359
                }
3360
            }
3361
        }
3362 8
        if ($firstNumberIn instanceof PhoneNumber && $secondNumberIn instanceof PhoneNumber) {
3363
            // We only care about the fields that uniquely define a number, so we copy these across
3364
            // explicitly.
3365 8
            $firstNumber = self::copyCoreFieldsOnly($firstNumberIn);
3366 8
            $secondNumber = self::copyCoreFieldsOnly($secondNumberIn);
3367
3368
            // Early exit if both had extensions and these are different.
3369 8
            if ($firstNumber->hasExtension() && $secondNumber->hasExtension() &&
3370 2
                $firstNumber->getExtension() != $secondNumber->getExtension()
3371 8
            ) {
3372 1
                return MatchType::NO_MATCH;
3373
            }
3374
3375 8
            $firstNumberCountryCode = $firstNumber->getCountryCode();
3376 8
            $secondNumberCountryCode = $secondNumber->getCountryCode();
3377
            // Both had country_code specified.
3378 8
            if ($firstNumberCountryCode != 0 && $secondNumberCountryCode != 0) {
0 ignored issues
show
Bug Best Practice 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...
Bug Best Practice 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...
3379 8
                if ($firstNumber->equals($secondNumber)) {
3380 5
                    return MatchType::EXACT_MATCH;
3381
                }
3382
3383 3
                if ($firstNumberCountryCode == $secondNumberCountryCode &&
3384 3
                    $this->isNationalNumberSuffixOfTheOther($firstNumber, $secondNumber)) {
3385
                    // A SHORT_NSN_MATCH occurs if there is a difference because of the presence or absence of
3386
                    // an 'Italian leading zero', the presence or absence of an extension, or one NSN being a
3387
                    // shorter variant of the other.
3388 2
                    return MatchType::SHORT_NSN_MATCH;
3389
                }
3390
                // This is not a match.
3391 1
                return MatchType::NO_MATCH;
3392
            }
3393
            // Checks cases where one or both country_code fields were not specified. To make equality
3394
            // checks easier, we first set the country_code fields to be equal.
3395 3
            $firstNumber->setCountryCode($secondNumberCountryCode);
3396
            // If all else was the same, then this is an NSN_MATCH.
3397 3
            if ($firstNumber->equals($secondNumber)) {
3398 1
                return MatchType::NSN_MATCH;
3399
            }
3400 3
            if ($this->isNationalNumberSuffixOfTheOther($firstNumber, $secondNumber)) {
3401 2
                return MatchType::SHORT_NSN_MATCH;
3402
            }
3403 1
            return MatchType::NO_MATCH;
3404
        }
3405
        return MatchType::NOT_A_NUMBER;
3406
    }
3407
3408
    /**
3409
     * Returns true when one national number is the suffix of the other or both are the same.
3410
     * @param PhoneNumber $firstNumber
3411
     * @param PhoneNumber $secondNumber
3412
     * @return bool
3413
     */
3414 4
    protected function isNationalNumberSuffixOfTheOther(PhoneNumber $firstNumber, PhoneNumber $secondNumber)
3415
    {
3416 4
        $firstNumberNationalNumber = trim((string)$firstNumber->getNationalNumber());
3417 4
        $secondNumberNationalNumber = trim((string)$secondNumber->getNationalNumber());
3418 4
        return $this->stringEndsWithString($firstNumberNationalNumber, $secondNumberNationalNumber) ||
3419 4
        $this->stringEndsWithString($secondNumberNationalNumber, $firstNumberNationalNumber);
3420
    }
3421
3422 4
    protected function stringEndsWithString($hayStack, $needle)
3423
    {
3424 4
        $revNeedle = strrev($needle);
3425 4
        $revHayStack = strrev($hayStack);
3426 4
        return strpos($revHayStack, $revNeedle) === 0;
3427
    }
3428
3429
    /**
3430
     * Returns true if the supplied region supports mobile number portability. Returns false for
3431
     * invalid, unknown or regions that don't support mobile number portability.
3432
     *
3433
     * @param string $regionCode the region for which we want to know whether it supports mobile number
3434
     *                    portability or not.
3435
     * @return bool
3436
     */
3437 3
    public function isMobileNumberPortableRegion($regionCode)
3438
    {
3439 3
        $metadata = $this->getMetadataForRegion($regionCode);
3440 3
        if ($metadata === null) {
3441
            return false;
3442
        }
3443
3444 3
        return $metadata->isMobileNumberPortableRegion();
3445
    }
3446
3447
    /**
3448
     * Check whether a phone number is a possible number given a number in the form of a string, and
3449
     * the region where the number could be dialed from. It provides a more lenient check than
3450
     * {@link #isValidNumber}. See {@link #isPossibleNumber(PhoneNumber)} for details.
3451
     *
3452
     * Convenience wrapper around {@link #isPossibleNumberWithReason}. Instead of returning the reason
3453
     * for failure, this method returns a boolean value.
3454
     * for failure, this method returns true if the number is either a possible fully-qualified number
3455
     * (containing the area code and country code), or if the number could be a possible local number
3456
     * (with a country code, but missing an area code). Local numbers are considered possible if they
3457
     * could be possibly dialled in this format: if the area code is needed for a call to connect, the
3458
     * number is not considered possible without it.
3459
     *
3460
     * Note: There are two ways to call this method.
3461
     *
3462
     * isPossibleNumber(PhoneNumber $numberObject)
3463
     * isPossibleNumber(string '+441174960126', string 'GB')
3464
     *
3465
     * @param PhoneNumber|string $number the number that needs to be checked, in the form of a string
3466
     * @param string|null $regionDialingFrom the region that we are expecting the number to be dialed from.
3467
     *     Note this is different from the region where the number belongs.  For example, the number
3468
     *     +1 650 253 0000 is a number that belongs to US. When written in this form, it can be
3469
     *     dialed from any region. When it is written as 00 1 650 253 0000, it can be dialed from any
3470
     *     region which uses an international dialling prefix of 00. When it is written as
3471
     *     650 253 0000, it can only be dialed from within the US, and when written as 253 0000, it
3472
     *     can only be dialed from within a smaller area in the US (Mountain View, CA, to be more
3473
     *     specific).
3474
     * @return boolean true if the number is possible
3475
     */
3476 57
    public function isPossibleNumber($number, $regionDialingFrom = null)
3477
    {
3478 57
        if ($regionDialingFrom !== null && is_string($number)) {
3479
            try {
3480 2
                return $this->isPossibleNumber($this->parse($number, $regionDialingFrom));
3481 1
            } catch (NumberParseException $e) {
3482 1
                return false;
3483
            }
3484
        } else {
3485 57
            $result = $this->isPossibleNumberWithReason($number);
0 ignored issues
show
Bug introduced by
It seems like $number can also be of type string; however, parameter $number of libphonenumber\PhoneNumb...sibleNumberWithReason() does only seem to accept libphonenumber\PhoneNumber, maybe add an additional type check? ( Ignorable by Annotation )

If this is a false-positive, you can also ignore this issue in your code via the ignore-type  annotation

3485
            $result = $this->isPossibleNumberWithReason(/** @scrutinizer ignore-type */ $number);
Loading history...
3486
            return $result === ValidationResult::IS_POSSIBLE
3487 57
                || $result === ValidationResult::IS_POSSIBLE_LOCAL_ONLY;
3488
        }
3489
    }
3490
3491
3492
    /**
3493
     * Check whether a phone number is a possible number. It provides a more lenient check than
3494
     * {@link #isValidNumber} in the following sense:
3495
     * <ol>
3496
     *   <li> It only checks the length of phone numbers. In particular, it doesn't check starting
3497
     *        digits of the number.
3498
     *   <li> It doesn't attempt to figure out the type of the number, but uses general rules which
3499
     *        applies to all types of phone numbers in a region. Therefore, it is much faster than
3500
     *        isValidNumber.
3501
     *   <li> For some numbers (particularly fixed-line), many regions have the concept of area code,
3502
     *        which together with subscriber number constitute the national significant number. It is
3503
     *        sometimes okay to dial only the subscriber number when dialing in the same area. This
3504
     *        function will return IS_POSSIBLE_LOCAL_ONLY if the subscriber-number-only version is
3505
     *        passed in. On the other hand, because isValidNumber validates using information on both
3506
     *        starting digits (for fixed line numbers, that would most likely be area codes) and
3507
     *        length (obviously includes the length of area codes for fixed line numbers), it will
3508
     *        return false for the subscriber-number-only version.
3509
     * </ol>
3510
     * @param PhoneNumber $number the number that needs to be checked
3511
     * @return int a ValidationResult object which indicates whether the number is possible
3512
     */
3513 59
    public function isPossibleNumberWithReason(PhoneNumber $number)
3514
    {
3515 59
        return $this->isPossibleNumberForTypeWithReason($number, PhoneNumberType::UNKNOWN);
3516
    }
3517
3518
    /**
3519
     * Check whether a phone number is a possible number of a particular type. For types that don't
3520
     * exist in a particular region, this will return a result that isn't so useful; it is recommended
3521
     * that you use {@link #getSupportedTypesForRegion} or {@link #getSupportedTypesForNonGeoEntity}
3522
     * respectively before calling this method to determine whether you should call it for this number
3523
     * at all.
3524
     *
3525
     * This provides a more lenient check than {@link #isValidNumber} in the following sense:
3526
     *
3527
     * <ol>
3528
     *   <li> It only checks the length of phone numbers. In particular, it doesn't check starting
3529
     *        digits of the number.
3530
     *   <li> For some numbers (particularly fixed-line), many regions have the concept of area code,
3531
     *        which together with subscriber number constitute the national significant number. It is
3532
     *        sometimes okay to dial only the subscriber number when dialing in the same area. This
3533
     *        function will return IS_POSSIBLE_LOCAL_ONLY if the subscriber-number-only version is
3534
     *        passed in. On the other hand, because isValidNumber validates using information on both
3535
     *        starting digits (for fixed line numbers, that would most likely be area codes) and
3536
     *        length (obviously includes the length of area codes for fixed line numbers), it will
3537
     *        return false for the subscriber-number-only version.
3538
     * </ol>
3539
     *
3540
     * @param PhoneNumber $number the number that needs to be checked
3541
     * @param int $type the PhoneNumberType we are interested in
3542
     * @return int a ValidationResult object which indicates whether the number is possible
3543
     */
3544 68
    public function isPossibleNumberForTypeWithReason(PhoneNumber $number, $type)
3545
    {
3546 68
        $nationalNumber = $this->getNationalSignificantNumber($number);
3547 68
        $countryCode = $number->getCountryCode();
3548
3549
        // Note: For regions that share a country calling code, like NANPA numbers, we just use the
3550
        // rules from the default region (US in this case) since the getRegionCodeForNumber will not
3551
        // work if the number is possible but not valid. There is in fact one country calling code (290)
3552
        // where the possible number pattern differs between various regions (Saint Helena and Tristan
3553
        // da Cuñha), but this is handled by putting all possible lengths for any country with this
3554
        // country calling code in the metadata for the default region in this case.
3555 68
        if (!$this->hasValidCountryCallingCode($countryCode)) {
3556 1
            return ValidationResult::INVALID_COUNTRY_CODE;
3557
        }
3558
3559 68
        $regionCode = $this->getRegionCodeForCountryCode($countryCode);
3560
        // Metadata cannot be null because the country calling code is valid.
3561 68
        $metadata = $this->getMetadataForRegionOrCallingCode($countryCode, $regionCode);
3562 68
        return $this->testNumberLength($nationalNumber, $metadata, $type);
3563
    }
3564
3565
    /**
3566
     * Attempts to extract a valid number from a phone number that is too long to be valid, and resets
3567
     * the PhoneNumber object passed in to that valid version. If no valid number could be extracted,
3568
     * the PhoneNumber object passed in will not be modified.
3569
     * @param PhoneNumber $number a PhoneNumber object which contains a number that is too long to be valid.
3570
     * @return boolean true if a valid phone number can be successfully extracted.
3571
     */
3572 1
    public function truncateTooLongNumber(PhoneNumber $number)
3573
    {
3574 1
        if ($this->isValidNumber($number)) {
3575 1
            return true;
3576
        }
3577 1
        $numberCopy = new PhoneNumber();
3578 1
        $numberCopy->mergeFrom($number);
3579 1
        $nationalNumber = $number->getNationalNumber();
3580
        do {
3581 1
            $nationalNumber = floor($nationalNumber / 10);
3582 1
            $numberCopy->setNationalNumber($nationalNumber);
3583 1
            if ($this->isPossibleNumberWithReason($numberCopy) == ValidationResult::TOO_SHORT || $nationalNumber == 0) {
3584 1
                return false;
3585
            }
3586 1
        } while (!$this->isValidNumber($numberCopy));
3587 1
        $number->setNationalNumber($nationalNumber);
3588 1
        return true;
3589
    }
3590
}
3591