update v 1.0.7.5

vendor/giggsey/libphonenumber-for-php/docs/ShortNumberInfo.md

@@ -0,0 +1,172 @@
+# ShortNumberInfo
+
+## Getting Started
+
+As with [PhoneNumberUtil](PhoneNumberUtil.md), ShortNumberInfo uses a singleton.
+
+```php
+$shortNumberUtil = \libphonenumber\ShortNumberInfo::getInstance();
+```
+
+## Example Numbers
+
+### `getExampleShortNumber()`
+
+Returns an example short phone number for the `$regionCode` supplied
+
+```php
+var_dump($shortNumberUtil->getExampleShortNumber('GB'));
+// string(3) "150"
+```
+
+### `getExampleShortNumberForCost()`
+
+Returns a valid short number for the specified `$regionCode` and `$cost` category.
+
+```php
+var_dump($shortNumberUtil->getExampleShortNumberForCost('GB', \libphonenumber\ShortNumberCost::TOLL_FREE));
+// string(6) "116000"
+
+var_dump($shortNumberUtil->getExampleShortNumberForCost('GB', \libphonenumber\ShortNumberCost::PREMIUM_RATE));
+// string(0) ""
+
+var_dump($shortNumberUtil->getExampleShortNumberForCost('US', \libphonenumber\ShortNumberCost::PREMIUM_RATE));
+// string(5) "24280"
+```
+
+## Emergency Numbers
+
+### `isEmergencyNumber()`
+
+Returns whether the supplied `$number` exactly matches an emergency service number for the `$region`.
+
+```php
+var_dump($shortNumberUtil->isEmergencyNumber('999', 'GB'));
+// bool(true)
+
+var_dump($shortNumberUtil->isEmergencyNumber('9999', 'GB'));
+// bool(false)
+```
+
+### `connectsToEmergencyNumber()`
+
+Checks whether the `$number` (when dialled) might connect to an emergency service within the given `$region`.
+
+```php
+var_dump($shortNumberUtil->connectsToEmergencyNumber('999', 'GB'));
+// bool(true)
+
+// Note, 999 is a GB emergency service, but additional digits after the 999
+// might be possible to dial.
+var_dump($shortNumberUtil->connectsToEmergencyNumber('999123', 'GB'));
+// bool(true)
+```
+
+## Short Number Validation
+
+### `isPossibleShortNumber()`
+
+Checks whether the specified `PhoneNumber` object is a possible short number.
+
+```php
+$phoneNumber = new \libphonenumber\PhoneNumber();
+$phoneNumber->setCountryCode(44);
+$phoneNumber->setNationalNumber(118118);
+
+var_dump($shortNumberUtil->isPossibleShortNumber($phoneNumber));
+// bool(true)
+```
+
+### `isPossibleShortNumberForRegion()`
+
+Checks whether the supplied `$shortNumber` (which can either be a string or a `PhoneNumber` object) is possible for the `$region`.
+
+```php
+
+$phoneNumber = new \libphonenumber\PhoneNumber();
+$phoneNumber->setCountryCode(44);
+$phoneNumber->setNationalNumber(118118);
+
+var_dump($shortNumberUtil->isPossibleShortNumberForRegion($phoneNumber, 'GB'));
+// bool(true)
+
+var_dump($shortNumberUtil->isPossibleShortNumberForRegion('1234', 'GB'));
+// bool(true)
+```
+
+### `isValidShortNumber()`
+
+Checks whether the specified `PhoneNumber` object is a valid short number.
+
+**Important:** This doesn't actually validate whether the number is in use. libphonenumber-for-php is only able to validate number patterns, and isn't able to check with telecommunication providers.
+
+```php
+$phoneNumber = new \libphonenumber\PhoneNumber();
+$phoneNumber->setCountryCode(44);
+$phoneNumber->setNationalNumber(118118);
+
+var_dump($shortNumberUtil->isValidShortNumber($phoneNumber));
+// bool(true)
+```
+
+### `isValidShortNumberForRegion()`
+
+Checks whether the supplied `$shortNumber` (which can either be a string or a `PhoneNumber` object) is valid for the `$region`.
+
+**Important:** As with `isValidShortNumber()`, this can not validate whether the number is actually in use.
+
+```php
+$phoneNumber = new \libphonenumber\PhoneNumber();
+$phoneNumber->setCountryCode(44);
+$phoneNumber->setNationalNumber(118118);
+
+var_dump($shortNumberUtil->isValidShortNumberForRegion($phoneNumber, 'GB'));
+// bool(true)
+
+var_dump($shortNumberUtil->isValidShortNumberForRegion('1234', 'GB'));
+// bool(false)
+```
+
+### `isCarrierSpecific()`
+
+Returns whether the supplied `PhoneNumber` is a carrier specific short number.
+
+```php
+$phoneNumber = new \libphonenumber\PhoneNumber();
+$phoneNumber->setCountryCode(1);
+$phoneNumber->setNationalNumber(611);
+
+var_dump($shortNumberUtil->isCarrierSpecific($phoneNumber));
+// (bool) true
+```
+
+## Expected Costs
+
+### `getExpectedCost()`
+
+Returns the expected cost (as a `ShortNumberCost` constant) of the supplied `PhoneNumber` short number.
+
+```php
+$phoneNumber = new \libphonenumber\PhoneNumber();
+$phoneNumber->setCountryCode(44);
+$phoneNumber->setNationalNumber(118118);
+
+var_dump($shortNumberUtil->getExpectedCost($phoneNumber, 'GB'));
+// int(10) (ShortNumberCost::UNKNOWN_COST)
+```
+
+### `getExpectedCostForRegion()`
+
+Returns the expected cost (as a `ShortNumberCost` constant) of the supplied `$number` (which can be a string or a `PhoneNumber` object).
+
+```php
+$phoneNumber = new \libphonenumber\PhoneNumber();
+$phoneNumber->setCountryCode(44);
+$phoneNumber->setNationalNumber(118118);
+
+var_dump($shortNumberUtil->getExpectedCostForRegion($phoneNumber, 'GB'));
+// int(10) (ShortNumberCost::UNKNOWN_COST)
+
+var_dump($shortNumberUtil->getExpectedCostForRegion('24280', 'US'));
+// int(4) (ShortNumberCost::PREMIUM_RATE)
+```