erichowey/nanp-number-formatter

Take a NANP phone number and return it in a variety of formats.

2.0.0 2021-10-12 17:06 UTC

Requires

• php: ^7.4 || ^8.0

Requires (Dev)

• phpunit/phpunit: ^9.0

MIT

• Eric Howey

• formatter
• number
• phone
• format
• nanp

README

This utility takes a NANP (North American Numbering Plan) phone number, parses it and returns the number in a variety of formats.

Install

You can install this package via composer

composer require erichowey/nanp-number-formatter

Supported Input Formats and Characters

• 10 Digit 2125550123
• 11 Digit 12125550123
• E.164 [phone]
• Parenthesis [phone]
• Dot 212.555.0123
• Hyphen 212-555-0123
• Space 212 555 0123
• Letters 1800FLOWERS

etc...

Outputted Formats

• E.164 [phone]
• Dot Format 212.555.0123
• Hyphen Format 212-555-0123
• National Format [phone]
• National Format Plus One 1 [phone]
• International Format [phone]
• 10 Digit 2125550123
• 11 Digit 12325550123
• URI tel:[phone]
• NPA 212
• NXX 555
• Line 0123

Example Usage

use Erichowey\NanpNumberFormatter\NanpNumberFormatter;
...
$number = NanpNumberFormatter::format("[phone]");

echo $number->e164; // [phone]
echo $number->nationalFormat; // [phone]
echo $number->nationalFormatPlusOne; // 1 [phone]
echo $number->internationalFormat; // [phone]
echo $number->dotFormat; // 212.555.0123
echo $number->hyphenFormat; // 212-555-0123
echo $number->tendigit; // 2125550123
echo $number->elevendigit; // 12125550123
echo $number->uri; // tel:[phone]
echo $number->npa; // 212
echo $number->nxx; // 555
echo $number->line; // 0123
...

Wildcards

Historically, NANP telephone number wildcards have been represented with the following characters: X for 0-9, N for 2-9 and occasionally Y for 1-9 in dialplan matching. Since this tool accepts letter input, these wildcard characters cannot be used. To utilize wildcard characters, set the second parameter of the format() method to true. Use * to represent a wildcard character.

$number = NanpNumberFormatter::format("(212) 555-****", true);

Errors

If an invalid or non nanp number is attempted to be formatted, a NanpNumberFormatterException will be thrown. They can be handled with the typical try/catch pattern:

try {
    $number = NanpNumberFormatter::format("1234");
} catch (NanpNumberFormatterException $e) {
    echo $e->getMessage(); // 1234 is less than 10 characters
}

Contributing

Contributions are welcome. Criticism is even more welcome. You're welcome to submit a PR or open an issue. Please conform to PSR-12 standards and create tests for your PR.

Testing

Run

./vendor/bin/phpunit