aklump/phone-number

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

0.0.9 2024-08-15 01:48 UTC

Requires

• php: >=7.3

Requires (Dev)

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

BSD-3-Clause

• Aaron Klump

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 this package:

   composer require aklump/phone-number:^0.0
   

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