aklump/phone-number

A lean, non-dependency PHP library to work with phone numbers.

0.0.10 2026-07-17 20:34 UTC

Requires

• php: >=7.4

Requires (Dev)

• aklump/phpswap: ^0.0
• phpunit/phpunit: ^9.6

BSD-3-Clause

• Aaron Klump

Published on Packagist.org on 2026-07-17 20:34 UTC

README

A lean, non-dependency PHP library to work with phone numbers. The focus of the library is on U.S. phone numbers only at this time. To work with international phone numbers you might try Phone Normalizer, from which we've taken the same formatting strategy. (Thank you, dmamontov and 1on.)

Install with Composer

1. Require the latest stable version:

   composer require aklump/phone-number:^0.0

2. ... or require the dev channel:

   composer config minimum-stability dev
   composer require aklump/phone-number:@dev

Usage

Formatting Numbers

• Tokens are:
  • #CC# for the country code.
  • #c# for the area code
  • ### (leftmost three) for the local exchange.
  • #### (rightmost four) for subscriber number.
• Pre-defined formats provided by \AKlump\PhoneNumber\PhoneNumberFormats
• Invalid phone numbers will not format, but throw an exception.
• To obtain a list of violations for an invalid phone number use the ::validate method.

$phone = (new \AKlump\PhoneNumber\USPhoneNumberFormatter();
$number = $phone->format('3608881223');
// '[phone]' === $formatted

If the context of your app is regional, you maybe want to assume a default area code.

$default_area_code = 360;
$phone = (new \AKlump\PhoneNumber\USPhoneNumberFormatter($default_area_code);

$number = $phone->format('8881223');
// '[phone]' === $formatted

Formatted for SMS

$number = $phone->format('888-1223', \AKlump\PhoneNumber\PhoneNumberFormats::SMS);
// '[phone]' === $number

Using Custom Formats

// Provide a custom default format.
$phone = (new \AKlump\PhoneNumber\USPhoneNumberFormatter(360, '+#CC#.#c#.###.####');
$number = $phone->format('888-1223');
// '+1.360.888.1223' === $number

Outside the Box Thinking

// Convert to a JSON string.
$phone = (new \AKlump\PhoneNumber\USPhoneNumberFormatter(360, \AKlump\PhoneNumber\PhoneNumberFormats::JSON);
$number = $phone->format('888-1223');
// '{"country":"+1","areaCode":206,"localExchange":555,"subscriberNumber":1212}' === $number

Validating Numbers

$phone = (new \AKlump\PhoneNumber\USPhoneNumberFormatter();
$violations = $phone->validate('3608881223');
foreach($violations as $violation) {
  echo $violation;
}
$is_valid = empty($violations);

• See also \AKlump\PhoneNumber\PhoneNumberViolations