oracular (3) Number::Phone.3pm.gz
NAME
Number::Phone - base class for Number::Phone::* modules
SYNOPSIS
In a sub-class ...
package Number::Phone::UK;
use base 'Number::Phone';
and to magically use the right subclass ...
use Number::Phone;
$daves_phone = Number::Phone->new('+442087712924');
$daves_other_phone = Number::Phone->new('+44 7979 866 975');
# alternatively Number::Phone->new('+44', '7979 866 975');
# or Number::Phone->new('UK', '07979 866 975');
if($daves_phone->is_mobile()) {
send_rude_SMS();
}
in the example, the +44 is recognised as the country code for the UK, so the appropriate country-specific
module is loaded if available.
If you pass in a bogus country code not recognised by Number::Phone::Country, the constructor will return
undef.
INCOMPATIBLE CHANGES
from version 4.0003 onwards
As of version 4.0003, alphabetic characters and underscores in phone numbers will cause a warning to be
emitted. The first release after August 2026 will upgrade those to be fatal errors.
from version 3.9002 onwards
3.9002 is the last version that supported perls with 32-bit integers.
from version 3.8000 onwards
3.8000 is a bit stricter about numbers and countries not matching in the constructor. This may affect
users who specify places like Guernsey but provide numbers from Jersey or the Isle of Man, all three of
which are separate jurisdictions squatting on random places all over the UK's number plan.
from version 3.6000 onwards
As of version 3.6000 the "areaname" method is documented as taking an optional language code. As far as I
can tell providing this new parameter to the method as provided by all the subclasses on the CPAN won't
do any harm.
from version 3.4004 onwards
The prefix codes in 3.4003 and earlier were managed by hand and so got out of date. After that release
they are mostly derived from libphonenumber. libphonenumber's data includes carrier selection codes when
they are mandatory for dialling so those are now included. This sometimes means that some random carrier
has been arbitrarily privileged over others.
from version 3.4000 to 3.4003
From version 3.4000 to 3.4003 inclusive we accepted any old garbage after +383 as being valid, as the
Kosovo numbering plan had not been published. Now that that has been published, we use libphonenumber
data, and validate against it.
until version 3.3000
We used to use KOS for the country code for Kosovo, that has now changed to XK. See
Number::Phone::Country.
until version 3.0014
Early versions of this module allowed what are now object methods to also be called as class methods or
even as functions. This was a bad design decision. Use of those calling conventions was deprecated in
version 2.0, released in January 2012, and started to emit warnings. All code to support those calling
conventions has now been removed.
COMPATIBILITY WITH libphonenumber
libphonenumber is a similar project for other languages, maintained by Google.
If you pass in a country code for which no supporting module is available, the constructor will try to
use a 'stub' class under Number::Phone::StubCountry::* that uses data automatically extracted from
Google's libphonenumber project. libphonenumber doesn't have enough data to support all the features of
Number::Phone. If you want to disable this, then pass 'nostubs' when you use the module:
use Number::Phone qw(nostubs);
Alternatively, if you want to *always* use data derived from libphonenumber, you should use the
Number::Phone::Lib module instead. This is a subclass of Number::Phone that will use the libphonenumber-
derived stub classes even when extra data is available in, for example, Number::Phone::UK. You might want
to do this for compatibility or performance. Number::Phone::UK is quite slow, because it uses a huge
database for some of its features.
PERL VERSIONS SUPPORTED
Your perl must support 64 bit ints.
Because they are not supported by some libraries that we depend on, perl versions below 5.14 are not
supported. If you have old versions of those libraries installed then Number::Phone may still work, but
because I can't automatically test on those older versions any more that is liable to change without
notice.
METHODS
All Number::Phone classes can implement the following object methods.
The implementations in the parent class all return undef unless otherwise noted.
Those methods whose names begin "is_" should return the following values:
undef
The truth or falsehood can not be determined;
0 (zero)
False - eg, is_personal() might return 0 for a number that is assigned to a government department.
1 (one)
True
IS_* methods
is_valid
The number is valid within the national numbering scheme. It may or may not yet be allocated, or it
may be reserved. Any number which returns true for any of the following methods will also be valid.
is_allocated
The number has been allocated to a telco for use. It may or may not yet be in use or may be
reserved.
is_in_use
The number has been assigned to a customer or is in use by the telco for its own purposes.
is_geographic
The number refers to a geographic area.
is_fixed_line
The number, when in use, can only refer to a fixed line.
is_mobile
The number, when in use, can only refer to a mobile phone.
is_pager
The number, when in use, can only refer to a pager.
is_ipphone
The number, when in use, can only refer to a VoIP service.
is_isdn
The number, when in use, can only refer to an ISDN service.
is_tollfree
Callers will not be charged for calls to this number under normal circumstances.
is_specialrate
The number, when in use, attracts special rates. For instance, national dialling at local rates, or
premium rates for services.
is_adult
The number, when in use, goes to a service of an adult nature, such as porn.
is_personal
The number, when in use, goes to an individual person.
is_corporate
The number, when in use, goes to a business.
is_government
The number, when in use, goes to a government department. Note that the emergency services are
considered to be a network service so should *not* return true for this method.
is_international
The number is charged like a domestic number (including toll-free or special rate), but actually
terminates in a different country. This covers the special dialling arrangements between Spain and
Gibraltar, and between the Republic of Ireland and Northern Ireland, as well as services such as the
various "Country Direct"-a-likes. See also the country() method.
is_network_service
The number is some kind of network service such as the operator, directory enquiries, emergency
services etc
is_drama
The number is for use in fiction, such as TV and Radio drama programmes. It will not be allocated
for use in real life.
OTHER NUMBER METADATA METHODS
country_code
The numeric code for this country. eg, 44 for the UK. Note that there is *no* + sign.
While the superclass does indeed implement this (returning undef) this is nonsense in just about all
cases, so you should always implement this.
regulator
Returns some text in an appropriate character set saying who the telecoms regulator is, with optional
details such as their web site or phone number.
areacode
Return the area code - if applicable - for the number. If not applicable, the superclass
implementation returns undef.
areaname
Return the name for the area code - if applicable. If not applicable, the superclass definition
returns undef. For instance, for a number beginning +44 20 it would return 'London'. Note that this
may return data in non-ASCII character sets.
This may take an optional language code such as 'de' or 'en'. If you provide that then you will get
back whatever the place name is in that language, if the data is available. If you don't provide it
then it will first look at your locale settings and try to find a name in an appropriate language,
and if nothing is found fall back to English.
location
This returns an approximate geographic location for the number if possible. Obviously this only
applies to fixed lines! The data returned is, if defined, a reference to an array containing two
elements, latitude and longitude, in degrees. North of the equator and East of Greenwich are
positive. You may optionally return a third element indicating how confident you are of the
location. Specify this as a number in kilometers indicating the radius of the error circle.
The superclass implementation returns undef, which is a reasonable default.
subscriber
Return the subscriber part of the number.
While the superclass implementation returns undef, this is nonsense in just about all cases, so you
should always implement this.
timezones
This returns a list-ref of the timezones that could be assoicated with a geographic number or with
the country for non geographic numbers. Returns undef in the case that possible timezones are
unknown.
Data is sourced from Google's libphonenumber project therefore implementation lies in the stub-
countries which return timezones e.g. Europe/London, America/New_York. Non-stub implementations by
default return their stub-country counterpart's result.
Results are sorted alphabetically.
This method should be considered experimental, and there may be some minor changes, especially for
international "country" codes and non-geographic numbers.
operator
Return the name of the telco assigned this number, in an appropriate character set and with optional
details such as their web site or phone number. Note that this should not take into account number
portability.
The superclass implementation returns undef, as this information is not easily available for most
numbering plans.
operator_ported
Return the name of the telco to whom this number has been ported. If it is known to have not been
ported, then return the same as operator() above.
The superclass implementation returns undef, indicating that you don't know whether the number has
been ported.
type
Return a listref of all the is_... methods above which are true. Note that this method should only
be implemented in the super-class. eg, for the number +44 20 87712924 this might return "[qw(valid
allocated geographic)]".
format
Return a sanely formatted E.123-compliant version of the number, complete with IDD code, eg for the
UK number (0208) 771-2924 it would return +44 20 8771 2924.
The superclass implementation returns undef, which is nonsense, so you should always implement this.
format_using
If you want something different from E.123, then pass this the name of a formatter to use.
For example, if you want to get "just the digits, ma'am", use the Raw formatter thus:
Number::Phone->new('+44 20 8771 2924')->format_using('Raw');
which will return:
2087712924
It is a fatal error to specify a non-existent formatter.
format_for_country
Given a country code (either two-letter ISO or numeric prefix), return the number formatted either
nationally-formatted, if the number is in the same country, or as a nationally-preferred
international number if not. Internally this uses the National and NationallyPreferredIntl
formatters. Beware of the potential performance hit!
country
The two letter ISO country code for the country in which the call will terminate. This is
implemented in the superclass and you will only have to implement your own version for countries
where part of the number range is overlayed with another country.
Exception: for the UK, return 'uk', not 'gb'.
Specifically, the superclass implementation looks at the class name and returns the last two-letter
code it finds. eg ...
from Number::Phone::UK, it would return UK
from Number::Phone::UK::IM, it would return IM
from Number::Phone::NANP::US, it would return US
from Number::Phone::FR::Full, it would return FR
translates_to
If the number forwards to another number (such as a special rate number forwarding to a geographic
number), or is part of a chunk of number-space mapped onto another chunk of number-space (such as
where a country has a shortcut to (part of) another country's number-space, like how Gibraltar used
to appear as an area code in Spain's numbering plan as well as having its own country code), then
this method may return an object representing the target number. Otherwise it returns undef.
The superclass implementation returns undef.
DATA SOURCES
data_source
Class method, return some hopefully useful text about the source of the data (if any) that drives a
country-specific module. The implementation in the base class returns undef as the base class itself
has no data source.
libphonenumber_tag
Class method which you should not over-ride, implemented in the base class. Returns the version of
libphonenumber whose metadata was used for this release of Number::Phone. NB that this is derived
from their most recent git tag, so may occasionally be a little ahead of the most recent
libphonenumber release as the tag gets created before their release is built.
The current version of this is also documented in Number::Phone::Data.
HOW TO DIAL FROM ONE NUMBER TO ANOTHER
dial_to
Takes another Number::Phone object as its only argument and returns a string showing how to dial from
the number represented by the invocant to that represented by the argument.
Examples:
Call from +44 20 7210 3613
to +44 1932 341 111
You dial 01932341111
Call from +44 20 7210 3613
to +44 1932 341 111
You dial 01932341111
Call from +44 20 7210 3613
to +1 202 224 6361
You dial 0012022246361
Call from +1 202 224 6361
to +44 20 7210 3613
You dial 011442072103613
Call from +44 7979 866975
to +44 7979 866976
You dial 07979 866976
This method is implemented in the superclass, but you may have to define certain other methods to
assist it. The algorithm is as follows:
international call
Append together the source country's international dialling prefix (usually 00), then the
destination country's country code, area code (if the country has such a thing), and subscriber
number.
domestic call, different area code
Call the object's intra_country_dial_to() method.
If it dies, return undef.
If it returns anything other than undef, return that.
If it returns undef, append together the country's out-of-area calling prefix (usually 0 or 1),
the destination area code and subscriber number.
domestic call, same area code
Call the object's intra_country_dial_to() method.
If it dies, return undef.
If it returns anything other than undef, return that.
If it returns undef, return the destination subscriber number.
intra_country_dial_to
Takes an object (which should be in the same country as the invocant) and returns either undef
(meaning "use the default behaviour") or a dialling string. If it dies this means "I don't know how
to dial this number".
The superclass implementation is to die.
Note that the meaning of undef is a bit different for this method.
Why die by default? Some countries have weird arrangements for dialling some numbers domestically.
In fact, both the countries I'm most familiar with do, so I assume that others do too.
CONSTRUCTOR
new Can be called with either one or two parameters. The *first* is an optional country code (see the
country() method). The other is a phone number. If a country code is specified, and a subclass for
that country is available, the phone number is passed to its constructor unchanged.
If only one parameter is passed, then we try to figure out which is the right country subclass to use
by pre-pending a + sign to the number if there isn't one, and looking the country up using
Number::Phone::Country. That gives us a two letter country code that is used to try to load the right
module. We then pass the number through to that module's constructor and return whatever it says
(which may be undef if you pass in an invalid number - see SUBCLASSING below).
The constructor returns undef if it can not figure out what country you're talking about, or an
object based on Google's libphonenumber data if there's no complete country-specific module
available.
It is generally assumed that numbers are complete and unambiguous - ie you can't normally pass just
the local part to the constructor if the number has an area code. Any subclass's constructor which
contravenes this should document it.
If you call it with two parameters, then the two must match. ie, if you do this:
Number::Phone->new("FR", "+441424220001")
you will get "undef" back because whiel the number is valid, it ain't French. This usually applies
to the case where a single country's number plan contains other jurisdictions, such as the case of
Guernsey, Jersey and the Isle of Man squatting on the United Kingdom's number plan. For example, this
fails, because the number is from Guernsey, not Jersey:
Number::Phone->new('JE', '01481256789')
For backward compatibility and convenience, however, if you ask for an object representing a number
in the "host" country but pass a number for the "sub-country" then you'll get back a valid object
representing the sub-country:
my $gg_number = Number::Phone->new('GB', '01481256789')
SUBCLASSING
Sub-classes should implement methods as above, including a new() constructor. The constructor should
take a single parameter, a phone number, and should validate that. If the number is valid (use your
is_valid() method!) then you can return a blessed object. Otherwise you should return undef.
The constructor *must* be capable of accepting a number with the + sign and the country's numeric code
attached, but should also accept numbers in the preferred local format (eg 01234 567890 in the UK, which
is the same number as +44 1234 567890) so that users can go straight to your class without going through
Number::Phone's magic country detector.
Subclasses' names should be Number::Phone::XX, where XX is the two letter ISO code for the country, in
upper case. So, for example, France would be FR and Ireland would be IE. As usual, the UK is an
exception, using UK instead of the ISO-mandated GB. NANP countries are also an exception, going like
Number::Phone::NANP::XX.
UPDATES
I release updates approximately every three months, including new data.
I will also do intercalary releases to fix *serious* bugs in the code and when *large* data updates (eg
when a country's numbering scheme changes) are brought to my attention.
I will not normally do a release just because a country has added some new number range. If this irks you
then I would welcome a discussion on how you can best write a patch, with tests, that will reliably
incorporate updated data from libphonenumber. Much of the needed code already exists in the repository
but it is not fit for end-user consumption.
BUGS/FEEDBACK
Please report bugs by at <https://github.com/DrHyde/perl-modules-Number-Phone/issues>, including, if
possible, a test case.
MAILING LIST
There is a mailing list for discussion and help. Please subscribe at
<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/number-phone>.
Kindly hosted by Shadowcat <http://scsys.co.uk>.
SEE ALSO
<https://github.com/googlei18n/libphonenumber>, a similar project for Java, C++ and Javascript.
Number::Phone imports its data.
SOURCE CODE REPOSITORY
<git://github.com/DrHyde/perl-modules-Number-Phone.git>
AUTHOR, COPYRIGHT and LICENCE
Copyright 2004 - 2024 David Cantrell <david@cantrell.org.uk> This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively. Some files are under the Apache licence, a copy of which can be found in the file Apache-2.0.txt.
CONSPIRACY
This module is also free-as-in-mason software.