Completed
Pull Request — master (#177)
by Joshua
16:33 queued 04:24
created

PhoneNumberUtil::formatInOriginalFormat()   D

Complexity

Conditions 18
Paths 47

Size

Total Lines 98
Code Lines 60

Duplication

Lines 0
Ratio 0 %

Code Coverage

Tests 53
CRAP Score 18.1119

Importance

Changes 0
Metric Value
c 0
b 0
f 0
dl 0
loc 98
rs 4.7996
ccs 53
cts 57
cp 0.9298
cc 18
eloc 60
nc 47
nop 2
crap 18.1119

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

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

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

function doesNotAcceptNull(stdClass $x) { }

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

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

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
693
    }
694
695
    /**
696
     * Returns the types for a country-code belonging to a non-geographical entity which the library
697
     * has metadata for. Will not include FIXED_LINE_OR_MOBILE (if numbers for this non-geographical
698
     * entity could be classified as FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would be
699
     * present) and UNKNOWN.
700
     *
701
     * @param int $countryCallingCode
702
     * @return array
703
     */
704 1
    public function getSupportedTypesForNonGeoEntity($countryCallingCode)
705
    {
706 1
        $metadata = $this->getMetadataForNonGeographicalRegion($countryCallingCode);
707 1
        if ($metadata === null) {
708 1
            return array();
709
        }
710
711 1
        return $this->getSupportedTypesForMetadata($metadata);
712
    }
713
714
    /**
715
     * Gets the length of the geographical area code from the {@code nationalNumber} field of the
716
     * PhoneNumber object passed in, so that clients could use it to split a national significant
717
     * number into geographical area code and subscriber number. It works in such a way that the
718
     * resultant subscriber number should be diallable, at least on some devices. An example of how
719
     * this could be used:
720
     *
721
     * <code>
722
     * $phoneUtil = PhoneNumberUtil::getInstance();
723
     * $number = $phoneUtil->parse("16502530000", "US");
724
     * $nationalSignificantNumber = $phoneUtil->getNationalSignificantNumber($number);
725
     *
726
     * $areaCodeLength = $phoneUtil->getLengthOfGeographicalAreaCode($number);
727
     * if ($areaCodeLength > 0)
728
     * {
729
     *     $areaCode = substr($nationalSignificantNumber, 0,$areaCodeLength);
730
     *     $subscriberNumber = substr($nationalSignificantNumber, $areaCodeLength);
731
     * } else {
732
     *     $areaCode = "";
733
     *     $subscriberNumber = $nationalSignificantNumber;
734
     * }
735
     * </code>
736
     *
737
     * N.B.: area code is a very ambiguous concept, so the I18N team generally recommends against
738
     * using it for most purposes, but recommends using the more general {@code nationalNumber}
739
     * instead. Read the following carefully before deciding to use this method:
740
     * <ul>
741
     *  <li> geographical area codes change over time, and this method honors those changes;
742
     *    therefore, it doesn't guarantee the stability of the result it produces.
743
     *  <li> subscriber numbers may not be diallable from all devices (notably mobile devices, which
744
     *    typically requires the full national_number to be dialled in most regions).
745
     *  <li> most non-geographical numbers have no area codes, including numbers from non-geographical
746
     *    entities
747
     *  <li> some geographical numbers have no area codes.
748
     * </ul>
749
     * @param PhoneNumber $number PhoneNumber object for which clients want to know the length of the area code.
750
     * @return int the length of area code of the PhoneNumber object passed in.
751
     */
752 1
    public function getLengthOfGeographicalAreaCode(PhoneNumber $number)
753
    {
754 1
        $metadata = $this->getMetadataForRegion($this->getRegionCodeForNumber($number));
755 1
        if ($metadata === null) {
756 1
            return 0;
757
        }
758
        // If a country doesn't use a national prefix, and this number doesn't have an Italian leading
759
        // zero, we assume it is a closed dialling plan with no area codes.
760 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...
761 1
            return 0;
762
        }
763
764 1
        $type = $this->getNumberType($number);
765 1
        $countryCallingCode = $number->getCountryCode();
766
767 1
        if ($type === PhoneNumberType::MOBILE
768
            // Note this is a rough heuristic; it doesn't cover Indonesia well, for example, where area
769
            // codes are present for some mobile phones but not for others. We have no better way of
770
            // representing this in the metadata at this point.
771 1
            && in_array($countryCallingCode, self::$GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES)
772
        ) {
773 1
            return 0;
774
        }
775
776 1
        if (!$this->isNumberGeographical($type, $countryCallingCode)) {
777 1
            return 0;
778
        }
779
780 1
        return $this->getLengthOfNationalDestinationCode($number);
781
    }
782
783
    /**
784
     * Returns the metadata for the given region code or {@code null} if the region code is invalid
785
     * or unknown.
786
     * @param string $regionCode
787
     * @return PhoneMetadata
788
     */
789 4904
    public function getMetadataForRegion($regionCode)
790
    {
791 4904
        if (!$this->isValidRegionCode($regionCode)) {
792 359
            return null;
793
        }
794
795 4891
        return $this->metadataSource->getMetadataForRegion($regionCode);
796
    }
797
798
    /**
799
     * Helper function to check region code is not unknown or null.
800
     * @param string $regionCode
801
     * @return bool
802
     */
803 4905
    protected function isValidRegionCode($regionCode)
804
    {
805 4905
        return $regionCode !== null && in_array($regionCode, $this->supportedRegions);
806
    }
807
808
    /**
809
     * Returns the region where a phone number is from. This could be used for geocoding at the region
810
     * level.
811
     *
812
     * @param PhoneNumber $number the phone number whose origin we want to know
813
     * @return null|string  the region where the phone number is from, or null if no region matches this calling
814
     * code
815
     */
816 2287
    public function getRegionCodeForNumber(PhoneNumber $number)
817
    {
818 2287
        $countryCode = $number->getCountryCode();
819 2287
        if (!isset($this->countryCallingCodeToRegionCodeMap[$countryCode])) {
820 4
            return null;
821
        }
822 2286
        $regions = $this->countryCallingCodeToRegionCodeMap[$countryCode];
823 2286
        if (count($regions) == 1) {
824 1714
            return $regions[0];
825
        } else {
826 596
            return $this->getRegionCodeForNumberFromRegionList($number, $regions);
827
        }
828
    }
829
830
    /**
831
     * @param PhoneNumber $number
832
     * @param array $regionCodes
833
     * @return null|string
834
     */
835 596
    protected function getRegionCodeForNumberFromRegionList(PhoneNumber $number, array $regionCodes)
836
    {
837 596
        $nationalNumber = $this->getNationalSignificantNumber($number);
838 596
        foreach ($regionCodes as $regionCode) {
839
            // If leadingDigits is present, use this. Otherwise, do full validation.
840
            // Metadata cannot be null because the region codes come from the country calling code map.
841 596
            $metadata = $this->getMetadataForRegion($regionCode);
842 596
            if ($metadata->hasLeadingDigits()) {
843 174
                $nbMatches = preg_match(
844 174
                    '/' . $metadata->getLeadingDigits() . '/',
845
                    $nationalNumber,
846
                    $matches,
847 174
                    PREG_OFFSET_CAPTURE
848
                );
849 174
                if ($nbMatches > 0 && $matches[0][1] === 0) {
850 174
                    return $regionCode;
851
                }
852 580
            } elseif ($this->getNumberTypeHelper($nationalNumber, $metadata) != PhoneNumberType::UNKNOWN) {
0 ignored issues
show
Bug introduced by
It seems like $metadata defined by $this->getMetadataForRegion($regionCode) on line 841 can be null; however, libphonenumber\PhoneNumb...::getNumberTypeHelper() does not accept null, maybe add an additional type check?

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

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

function doesNotAcceptNull(stdClass $x) { }

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

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

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

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

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

function doesNotAcceptNull(stdClass $x) { }

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

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

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

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

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

function doesNotAcceptNull(stdClass $x) { }

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

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

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

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

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

function doesNotAcceptNull(stdClass $x) { }

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

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

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

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

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

function doesNotAcceptNull(stdClass $x) { }

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

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

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

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

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


switch ($expr) {
    default:

        doSomething(); //wrong
        break;
}

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

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

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

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

function doesNotAcceptNull(stdClass $x) { }

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

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

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

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

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

function doesNotAcceptNull(stdClass $x) { }

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

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

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

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

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

function doesNotAcceptNull(stdClass $x) { }

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

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

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

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

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

An additional type check may prevent trouble.

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

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

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

function doesNotAcceptNull(stdClass $x) { }

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

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

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