README

The official PHP SDK for the E164 API — phone number validation and network lookup.

Requirements

• PHP 8.1+
• ext-json

Installation

composer require e164-com/e164-php-sdk

Quick Start

use Vendor\E164\E164;

$e164 = new E164();
$result = $e164->lookup('441133910781');

echo $result->getType();            // "GEOGRAPHIC"
echo $result->getCallingCode();     // "44"
echo $result->getIso3();            // "GBR"
echo $result->getOperatorBrand();   // "BT"

Authentication (Optional)

The E164 API works without authentication, but if you have an API key you can pass it as the second parameter:

$e164 = new E164(null, 'your-api-key');
$result = $e164->lookup('441133910781');

This sends the key as an X-API-Key header with every request.

Working with Results

$result = $e164->lookup('441133910781');

// Number identification
$result->getPrefix();          // "44113391"
$result->getCallingCode();     // "44"
$result->getIso3();            // "GBR"
$result->getType();            // "GEOGRAPHIC"
$result->getLocation();        // Location if available

// Network details
$result->getTadig();           // TADIG code
$result->getMccmnc();          // "234"
$result->getOperatorBrand();   // "BT"
$result->getOperatorCompany(); // "BT"

// Number length constraints
$result->getTotalLengthMin();  // "12"
$result->getTotalLengthMax();  // "12"

// Metadata
$result->getWeight();          // "11"
$result->getSource();          // "e164.com"

Input Format

The SDK accepts phone numbers in various formats. Non-numeric characters (except +) are stripped automatically:

$e164->lookup('441133910781');      // digits only
$e164->lookup('+441133910781');     // with + prefix
$e164->lookup('+44-113-391-0781'); // formatted

Custom HTTP Client

You can inject your own Guzzle client for custom configuration (proxies, timeouts, etc.):

use GuzzleHttp\Client;
use Vendor\E164\E164;

$client = new Client([
    'timeout' => 10,
    'headers' => [
        'User-Agent' => 'MyApp/1.0',
    ],
]);

$e164 = new E164($client);

Error Handling

use Vendor\E164\E164;
use Vendor\E164\Exception\InvalidPhoneNumberException;
use Vendor\E164\Exception\ApiException;

try {
    $result = $e164->lookup('441133910781');
} catch (InvalidPhoneNumberException $e) {
    // Phone number is empty, non-numeric, or not found
} catch (ApiException $e) {
    // HTTP request failed (network error, timeout, server error)
}

Both exceptions extend RuntimeException, so you can catch them individually or together.

Running Tests

# Install dependencies
composer install

# Run tests
vendor/bin/phpunit

# Run static analysis
vendor/bin/phpstan analyse

Contributing

Fork the repository and submit a pull request. Please include tests for any new features or bug fixes.

License

MIT