Reference
PhoneNumber API
use Devix\Phone\PhoneNumber;
$phone = PhoneNumber::parse('050 123 4567', 'AE'); // never throws
$phone = PhoneNumber::from('+971501234567'); // throws InvalidPhoneNumber (with ->reason)
$phone = PhoneNumber::tryFrom($input, 'AE'); // null unless valid
What it is
| Method | Example |
|---|---|
isValid() |
true |
isPossible() |
true — right length for its country |
reason() |
Reason::TooShort |
type() |
NumberType::Mobile |
isMobile(), isFixed(), isType('voip', 'toll_free') |
US and Canada numbers count as both |
country() |
"AE" |
isCountry('AE', 'SA') |
true |
callingCode() |
"971" |
nationalNumber() |
"501234567" |
extension() |
"12" or null |
wasInternational() |
whether the input had + or 00 |
Formats
| Method | Output |
|---|---|
e164() |
+971501234567 |
international() |
+971 50 123 4567 |
national() |
050 123 4567 |
rfc3966() |
tel:+971-50-123-4567 |
format('national') |
any of the above by name |
formatFor('AE') |
national for the same country, international otherwise |
telUrl() |
tel:+971501234567 |
whatsappUrl('Hello') |
https://wa.me/971501234567?text=Hello |
masked() |
+971 50 ••• 4567 — first group and last four digits stay |
(string) $phone |
E.164, or the original input when incomplete |
Comparing
$phone->equals('050-123-4567'); // read with $phone's country
$phone->equals('0501234567', 'AE');
Reasons
Reason has the same values as the widget's reason: valid, empty, too_short, too_long,
invalid_length, invalid_country_code, invalid_number, possible_local_only, not_allowed_type.
The rule adds not_allowed_country and not_international.
Countries
use Devix\Phone\Countries;
Countries::all('ar'); // [['code' => 'AE', 'name' => 'الإمارات العربية المتحدة', 'dialCode' => '971', …], …]
Countries::search('uk'); // United Kingdom first — also "+44", "brit", "united k"
Countries::find('pk'); // ['code' => 'PK', 'name' => 'Pakistan', 'dialCode' => '92', …]
Names come from ext-intl when it's installed.
Example numbers
use Devix\Phone\Core\Engine;
use Devix\Phone\NumberType;
Engine::default()->exampleNumber('PK', NumberType::Mobile, national: false); // "+92 301 2345678"
Performance
Rules load one country at a time, from plain PHP arrays that OPcache keeps in memory. Validating a UAE number reads two files: the 11 KB calling-code index and the 1.7 KB UAE rules. A warm parse takes about 15 microseconds (PHP 8.3 on an Apple-silicon laptop).
Updated 12 Sep 2026