NAME
Number::MuPhone - parsing and using phone numbers in pure Perl
NOTE: this is a full rewrite and is not backwards compatible with earlier versions of this module.
DESCRIPTION
Parse, validate (loosely in some cases) and display phone numbers as expected.
This has stripped down functionality compared to libphonenumber, but it is also Pure Perl (TM), is a bit simpler to use, and contains the core functionality needed by common use cases.
If you have functionality requests, please let me know: <clive.holloway@gmail.com>
All number regexes are derived from the XML file supplied by:
https://github.com/google/libphonenumber/BASIC USAGE
Instantiate an instance using one of the following syntaxes
# single arg: E.123 formatted number, scalar shortcut
my $num = Number::MuPhone->new('+1 203 503 1199');
# single arg: E.123 formatted number, hashref format
my $num = Number::MuPhone->new({
number => '+1 203 503 1199'
});
# double arg, number and country - number can be in local or E.123 format, scalar args
my $num = Number::MuPhone->new('+1 203 503 1199','US");
my $num = Number::MuPhone->new('(203) 503-1199','US');
# double arg, number and country - number can be in local or E.123 format, hashref args
my $num = Number::MuPhone->new({
number => '+1 203 503 1199'
country => 'US',
});
my $num = Number::MuPhone->new({
number => '(203) 503-1199'
country => 'US',
});
# after instantiation, check all is well before using the object
if ($num->error) {
# process the error
}KEEPING UP TO DATE WITH CHANGES...
The data used to validate and format the phone numbers comes fropm Google's libphonenumber:
TODO: add URL
This distribution comes with a reasonably recent copy of the libphonenumber source XML, but you can also set up a cron to update your source data weekly, to ensure you don't have problems with new area codes as they get added (this happens probably more often than you think).
By default, MuPhone's update script (perl-muphone-build-data) will create a ~/.muphon directory and dump everything in there if you choose to update periodically (or when starting a Docker container, say)
If you want to store the data elsewhere, set the MUPHONE_BASE_DIR env var to specify where you want it stored. Wherever you store it, the directory must be writeable by the user.
Currently, the extractor script only grabs the data we need, and removes spacing, to keep the size down.
If you want to examine all available data, set $DEBUG=1 (add in padding) and set $STRIP_SUPERFLUOUS_DATA=0 in the script and run it again.
for the following, paths are relative to the ~/.muphone or $ENV{MUPHONE_BASE_DIR} dirs as appropriate
./etc/PhoneNumberMetadata.xml - the libphonenumber source XML file ./lib/NumberMuPhoneData.pm - the generated Number::MuPhone::Data ./t/check_data_module.t - a little sanity script that runs after creating the data file
Initial run
Optionally, set the MUPHONE_BASE_DIR environment variable to point to your config directory (must be writeable). Otherwise, ~/.muphone will get used (default).
As the user, run:
perl-muphone-build-data
Confirm the tests pass and the files are created (if not error output, tests passed).
Set up the cron to run weekly to update the data
# using default data dir 0 5 * * 1 /usr/local/bin/perl-muphone-build-data
# using user specific data dir 0 5 * * 1 MUPHONE_BASE_DIR=/path/to/config /usr/local/bin/perl-muphone-build-data
PUBLIC ATTRIBUTES
number
The raw number sent in at instantiation - not needed (outside of logging, maybe)
extension
Extenstion number (digits only)
country
The 2 character country code sent in instantiation, or inferred from an E.123 number
error
If the args don't point to a valid number at instantiation, this error will be set
country_name
Full text name of country()
country_code
1-3 digit country code
national_dial
How you would dial this number within the country (including national dial code)
national_display
Display this number in the national number format
national_display
Display this number in the international number format (E.123)
e164
The number in E.164 format (+$COUNTRY_CODE$NUMBER[;ext=$EXTENSION])
e164_no_ext
The number in E.164 format, but with no extension (+$COUNTRY_CODE$NUMBER)
METHODS
dial_from
How to dial the number from the number/country sent in as an arg. eg
my $uk_num1 = Number::MuPhone->new({ country => 'GB', number => '01929 552699' });
my $uk_num2 = Number::MuPhone->new({ country => 'GB', number => '01929 552698' });
my $us_num = Number::MuPhone->new({ country => 'US', number => '203 503 1234' });
# these all have the same output (01929552699)
my $dial_from_uk = $uk_num1->dial_from($uk_num2);
my $dial_from_uk = $uk_num1->dial_from('GB');
my $dial_from_uk = $uk_num1->dial_from('+441929 552698');
# similarly, dialling the number from the US (011441929552699)
my $dial_from_us = $uk_num1->dial_from($us_num);
my $dial_from_us = $uk_num1->dial_from('US');
my $dial_from_us = $uk_num1->dial_from('+1 203 503 1234');display_from
How to display the number for the number/country sent in as an arg. eg
my $uk_num1 = Number::MuPhone->new({ country => 'GB', number => '01929 552699' });
my $uk_num2 = Number::MuPhone->new({ country => 'GB', number => '01929 552698' });
my $us_num = Number::MuPhone->new({ country => 'US', number => '203 503 1234' });
# these all have the same output (01929 552699)
my $display_from_uk = $uk_num1->display_from($uk_num2);
my $display_from_uk = $uk_num1->display_from('GB');
my $display_from_uk = $uk_num1->display_from('+441929 552698');
# similarly, dialling the number from the US (01144 1929 552699)
my $display_from_us = $uk_num1->display_from($us_num);
my $display_from_us = $uk_num1->display_from('US');
my $display_from_us = $uk_num1->display_from('+1 203 503 1234');