Skip to main content
This guide walks you through the essential operations for working with international phone numbers using libphonenumber for PHP.

​
Basic Workflow

1

Get PhoneNumberUtil Instance

The PhoneNumberUtil class is the main entry point for all phone number operations. Get a singleton instance:
<?php
require 'vendor/autoload.php';

use libphonenumber\PhoneNumberUtil;
use libphonenumber\NumberParseException;
use libphonenumber\PhoneNumberFormat;

$phoneUtil = PhoneNumberUtil::getInstance();
The getInstance() method returns a singleton, so you can call it multiple times without performance concerns.
2

Parse a Phone Number

Parse a phone number string into a PhoneNumber object. You need to provide the number and a region code:
try {
    // Parse with region code
    $swissNumber = $phoneUtil->parse("044 668 18 00", "CH");
    
    // Parse international format (region code can be null)
    $ukNumber = $phoneUtil->parse("+44 117 496 0123", null);
    
    // Parse with different region
    $usNumber = $phoneUtil->parse("+1 650 253 0000", "US");
} catch (NumberParseException $e) {
    echo "Error parsing number: " . $e->getMessage();
}
If the number is in international format (starts with +), the region code can be null. Otherwise, the region code helps determine the correct country.
3

Validate the Number

Check if the parsed phone number is valid:
// Check if number is valid
$isValid = $phoneUtil->isValidNumber($swissNumber);
if ($isValid) {
    echo "The number is valid!\n";
} else {
    echo "The number is not valid.\n";
}

// Check if number is possible (lighter validation)
$isPossible = $phoneUtil->isPossibleNumber($swissNumber);

// Check if valid for specific region
$isValidForRegion = $phoneUtil->isValidNumberForRegion($ukNumber, "GB");
isValidNumber() validates number patterns but cannot check if a number is actually in use. It only verifies that the number follows the rules for that country.
4

Format the Number

Format the phone number in different styles:
// E.164 format (international standard)
echo $phoneUtil->format($swissNumber, PhoneNumberFormat::E164);
// Output: +41446681800

// International format (human-readable)
echo $phoneUtil->format($swissNumber, PhoneNumberFormat::INTERNATIONAL);
// Output: +41 44 668 18 00

// National format (as dialed within the country)
echo $phoneUtil->format($swissNumber, PhoneNumberFormat::NATIONAL);
// Output: 044 668 18 00

// RFC3966 format (for tel: URIs)
echo $phoneUtil->format($swissNumber, PhoneNumberFormat::RFC3966);
// Output: tel:+41-44-668-18-00
5

Format for International Dialing

Format a number as it would be dialed from another country:
// How to dial from the United States
echo $phoneUtil->formatOutOfCountryCallingNumber($swissNumber, "US");
// Output: 011 41 44 668 18 00

// How to dial from Great Britain
echo $phoneUtil->formatOutOfCountryCallingNumber($swissNumber, "GB");
// Output: 00 41 44 668 18 00

// Dialing from within Switzerland
echo $phoneUtil->formatOutOfCountryCallingNumber($swissNumber, "CH");
// Output: 044 668 18 00

​
Complete Example

Here’s a complete working example that demonstrates parsing, validation, and formatting: 
<?php
require 'vendor/autoload.php';

use libphonenumber\PhoneNumberUtil;
use libphonenumber\NumberParseException;
use libphonenumber\PhoneNumberFormat;

// Get PhoneNumberUtil instance
$phoneUtil = PhoneNumberUtil::getInstance();

// Parse a phone number
$numberString = "044 668 18 00";
$regionCode = "CH";

try {
    $phoneNumber = $phoneUtil->parse($numberString, $regionCode);
    
    // Validate the number
    if ($phoneUtil->isValidNumber($phoneNumber)) {
        echo "Valid phone number!\n\n";
        
        // Format in different styles
        echo "E.164: " . $phoneUtil->format($phoneNumber, PhoneNumberFormat::E164) . "\n";
        echo "International: " . $phoneUtil->format($phoneNumber, PhoneNumberFormat::INTERNATIONAL) . "\n";
        echo "National: " . $phoneUtil->format($phoneNumber, PhoneNumberFormat::NATIONAL) . "\n";
        
        // Get additional information
        $region = $phoneUtil->getRegionCodeForNumber($phoneNumber);
        echo "\nRegion: " . $region . "\n";
        
        $numberType = $phoneUtil->getNumberType($phoneNumber);
        echo "Type: " . $numberType . "\n";
    } else {
        echo "Invalid phone number.\n";
    }
} catch (NumberParseException $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

​
Error Handling

Always wrap phone number parsing in a try-catch block to handle invalid input: 
try {
    $phoneNumber = $phoneUtil->parse($input, $region);
} catch (NumberParseException $e) {
    switch ($e->getErrorType()) {
        case NumberParseException::INVALID_COUNTRY_CODE:
            echo "Invalid country code";
            break;
        case NumberParseException::NOT_A_NUMBER:
            echo "Not a valid phone number";
            break;
        case NumberParseException::TOO_SHORT_NSN:
            echo "Number is too short";
            break;
        case NumberParseException::TOO_LONG:
            echo "Number is too long";
            break;
        default:
            echo "Parse error: " . $e->getMessage();
    }
}
The NumberParseException includes detailed error types to help you provide specific feedback to users.

​
Best Practices

Always Validate

Parse the number first, then validate it with isValidNumber() before storing or using it.

Use E.164 Format

Store phone numbers in E.164 format (+41446681800) for consistency and international compatibility.

Handle Exceptions

Always catch NumberParseException when parsing user input to gracefully handle invalid numbers.

Provide Region Context

When parsing national numbers, always specify the region code to ensure accurate parsing.

​
Next Steps

Now that you know the basics, explore more advanced features:

Phone Number Geolocation

Get geographic information from phone numbers

Carrier Mapping

Identify the carrier for mobile numbers

Timezone Mapping

Find timezones associated with phone numbers

API Reference

Complete PhoneNumberUtil documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us