Documentation

Phones
in package

Helpers for common phone number functions

RECOMMENDATION: In your data, store a phone and a phone_code side by side Use Phones::compoundFormField() to render a compound form field for a phone number Run the phone value through one of the cleanNumber helpers to get a clean number to store

USAGE: Use the Phones::compareNumbers() helper to compare two phone numbers Use the Phones::compareNumbersWithCode() helper to compare two phone numbers by country code string

Table of Contents

Constants

NORMALIZE  : mixed = [' ' => '/\s+/u', '-' => '/\p{Pd}+/u', '(' => '...
Normalisation patterns.

Methods

cleanNumber()  : string
Trim, clean + normalise.
cleanStripCountryCode()  : string
Clean a phone number then remove leading 0, +, 00, country code and non-numeric characters
compareNumbers()  : bool
Compare two phone numbers, using default config country code
compareWithCode()  : bool
Compare two phone numbers by their clean numbers, using country code strings
compoundFormField()  : string
Render a compound form field for a phone number. Data should come from `Form`
countryPhoneCodeOptGroups()  : array<string|int, mixed>
Get a list of country codes and their names
format()  : string
Format a phone number.
getCountryPhoneCodeOptions()  : array<string|int, mixed>
Get a list of country codes and their names for dropdown use
getNumberType()  : string
The number type as a string.
isMobileNumber()  : bool
Is this a mobile number?
lookupCountry()  : string|null
Get the alpha-2 country code.
lookupRegion()  : string
Get the region name.
numberWithCountryCode()  : string
Add a country phone code to a phone number
parse()  : PhoneNumber
Internal parser with cleaning, returning a lib PhoneNumber.
validate()  : mixed
A sprout compatible validator.
getDefaultCountryAlpha2()  : string
Get the default country code in alpha2 based on alpha3 core config

Constants

NORMALIZE

Normalisation patterns.

public mixed NORMALIZE = [' ' => '/\s+/u', '-' => '/\p{Pd}+/u', '(' => '/\p{Ps}+/u', ')' => '/\p{Pe}+/u', '' => '/[\p{Cc}\p{Cf}]+/u']

https://www.php.net/manual/en/regexp.reference.unicode.php#128778

Methods

cleanNumber()

Trim, clean + normalise.

public static cleanNumber(string $number[, int $form = Normalizer::NFC ]) : string

Our data can get pretty dirty. So dirty that our formatter/parser library can't do the basics.

This doesn't normalise aggressively, only to get some characters codes into basic ASCII. We leave the rest to the parser.

Parameters
$number : string
$form : int = Normalizer::NFC

Normalizer::NFC

Return values
string

cleanStripCountryCode()

Clean a phone number then remove leading 0, +, 00, country code and non-numeric characters

public static cleanStripCountryCode(string $number, string $phone_code[, int $form = Normalizer::NFC ]) : string
Parameters
$number : string
$phone_code : string
$form : int = Normalizer::NFC

Normalizer::NFC

Return values
string

compareNumbers()

Compare two phone numbers, using default config country code

public static compareNumbers(string $number_1, string $number_2) : bool

Note: it's better to specify your country code wherever possible, using self::compareWithCode

Parameters
$number_1 : string
$number_2 : string
Return values
bool —

Whether the numbers are the same

compareWithCode()

Compare two phone numbers by their clean numbers, using country code strings

public static compareWithCode(string $number_1, string $code_1, string $number_2, string $code_2) : bool
Parameters
$number_1 : string
$code_1 : string
$number_2 : string
$code_2 : string
Return values
bool —

Whether the numbers are the same

compoundFormField()

Render a compound form field for a phone number. Data should come from `Form`

public static compoundFormField(bool $required[, string $label = null ][, array<string|int, mixed>|null $field_names = null ][, array<string|int, mixed>|null $common = null ]) : string
Parameters
$required : bool
$label : string = null
$field_names : array<string|int, mixed>|null = null

Optionally override the default field names [phone field, phone_code field]

$common : array<string|int, mixed>|null = null

Optionally override the default list of common country codes

Return values
string

countryPhoneCodeOptGroups()

Get a list of country codes and their names

public static countryPhoneCodeOptGroups([array<string|int, mixed>|null $common = null ]) : array<string|int, mixed>

Set common to an explicitly empty array [] for a single level list

Parameters
$common : array<string|int, mixed>|null = null

Override the default list of common country codes, using alpha3 codes

Return values
array<string|int, mixed>

format()

Format a phone number.

public static format(string $number[, int|PhoneNumberFormat $format = PhoneNumberFormat::E164 ]) : string
Parameters
$number : string
$format : int|PhoneNumberFormat = PhoneNumberFormat::E164
Tags
throws
NumberParseException
Return values
string

getCountryPhoneCodeOptions()

Get a list of country codes and their names for dropdown use

public static getCountryPhoneCodeOptions() : array<string|int, mixed>
Return values
array<string|int, mixed>

getNumberType()

The number type as a string.

public static getNumberType(string $number) : string
  • FIXED_LINE
  • MOBILE
  • FIXED_LINE_OR_MOBILE
  • TOLL_FREE
  • PREMIUM_RATE
  • SHARED_COST
  • VOIP
  • PERSONAL_NUMBER
  • PAGER
  • UAN
  • UNKNOWN
  • EMERGENCY
  • VOICEMAIL
  • SHORT_CODE
  • STANDARD_RATE
Parameters
$number : string
Tags
throws
NumberParseException
Return values
string

isMobileNumber()

Is this a mobile number?

public static isMobileNumber(string $number) : bool
Parameters
$number : string
Tags
throws
NumberParseException
Return values
bool

lookupCountry()

Get the alpha-2 country code.

public static lookupCountry(string $number) : string|null

Unlike the other helpers, this doesn't use the default country code.

Parameters
$number : string
Tags
throws
NumberParseException
Return values
string|null —

ISO alpha-2 country code

lookupRegion()

Get the region name.

public static lookupRegion(string $number[, string $locale = 'en' ]) : string

Like; Adelaide, Redfern, India, New Zealand, etc.

Parameters
$number : string
$locale : string = 'en'
Tags
throws
NumberParseException
Return values
string

numberWithCountryCode()

Add a country phone code to a phone number

public static numberWithCountryCode(string $phone_number, string $phone_code) : string
Parameters
$phone_number : string
$phone_code : string
Return values
string

parse()

Internal parser with cleaning, returning a lib PhoneNumber.

public static parse(PhoneNumberUtil $lib, string $number, string $country) : PhoneNumber
Parameters
$lib : PhoneNumberUtil
$number : string
$country : string

ISO alpha-2 country code

Tags
throws
NumberParseException
Return values
PhoneNumber

validate()

A sprout compatible validator.

public static validate(string $number[, string|null $country = null ]) : mixed
Parameters
$number : string
$country : string|null = null
Tags
throws
ValidationException

getDefaultCountryAlpha2()

Get the default country code in alpha2 based on alpha3 core config

private static getDefaultCountryAlpha2() : string
Return values
string
On this page

Search results