Number::Phone(3pm)

📦
version 4.0011 · 6 versions
, in ubuntu stonking

💖 Number::Phone 💖

okay so bestie, welcome to Number::Phone(3pm) — that's the User Contributed Perl Documentation version, and she is long, so buckle up. This is the base class for Number::Phone::* modules and she is the mother of the whole phone-number friend group. 🎀

✨ NAME ✨

Number::Phone — the base class for Number::Phone::* modules. she's giving matriarch, she's giving foundation, everyone else is her subclasses. 💅

🌸 SYNOPSIS 🌸

first up, if you're making a subclass, you do it like this:

package Number::Phone::UK;
use base 'Number::Phone';

and then if you just want Perl to magically pick the right subclass for you (yes bestie, magically, she does the work so you don't have to):

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();
}

so in that example, that +44 gets recognised as the country code for the UK, and then the appropriate country-specific module gets loaded — if it's available, no cap.

and listen: if you pass in a bogus country code that Number::Phone::Country doesn't recognise? the constructor just returns undef. silent, no drama, just ✨nothing✨.

also MSISDN format is supported. periodt. 💜

😭 INCOMPATIBLE CHANGES 😭

this section is the "we need to talk" of the manpage. read it, bestie, fr fr.

from version 4.0003 onwards

as of version 4.0003, alphabetic characters and underscores in phone numbers will cause a warning to be emitted. and then — mark your calendar — the first release after August 2026 will upgrade those to be fatal errors. 💀 so like. fix it now.

from version 3.9002 onwards

3.9002 is the last version that supported perls with 32-bit integers. RIP to her 🫶

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 — and yes, all three of those are separate jurisdictions squatting on random places all over the UK's number plan. not me being chaotic with the numbering 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. slay.

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're 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. it is what it is 💅

from version 3.4000 to 3.4003

from version 3.4000 to 3.4003 inclusive, we accepted literally any old garbage after +383 as being valid, because the Kosovo numbering plan hadn't been published yet. now that it has been published, we use libphonenumber data and validate against it. glow-up complete. ✨

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. she's gone, bestie, she's not coming back. 🦋

🌈 COMPATIBILITY WITH libphonenumber 🌈

libphonenumber is a similar project for other languages, maintained by Google. so like, the cool older cousin. 😌

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. but heads up: libphonenumber doesn't have enough data to support all the features of Number::Phone. so if you want to disable this behaviour, 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. that one's 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 wanna do this for compatibility or performance. Number::Phone::UK is quite slow, because she uses a huge database for some of her features. she's doing a lot, okay, she's carrying the team. 😤

as an exception, it will always use the libphonenumber-derived stub for Irish numbers, even if Number::Phone::IE is installed. that module hasn't been maintained for a long time. sorry bestie. 🍓

🧚 PERL VERSIONS SUPPORTED 🧚

your perl must support 64 bit ints. non-negotiable.

and 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. so like. don't get comfy. 💀

🎀 METHODS 🎀

all Number::Phone classes can implement the following object methods.

the implementations in the parent class all return undef unless otherwise noted. she's the base class, she's not doing the work, she's delegating.

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. (she's retro, I respect it.)
  • 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. free is free bestie 💖
  • 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. 🙈 okay moving on
  • 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 the Republic of Ireland and Northern Ireland, and between Italy and San Marino, 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. main character numbers only, literally. 🎬

💜 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), that 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. she's multilingual, she's trying her best 🦋

  • 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 associated 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 the 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. 💅

(bestie don't go anywhere — there's more of this page coming, we're only getting started 🌸)

Okay so the superclass just hands you back undef here, which is its lil way of saying "bestie I have literally no idea whether this number has been ported" 🫠

🎀 type

Hands you back a listref of every single is_... method from up above that's true for this number.

Heads up though — this one should only ever be implemented in the super-class, don't go rogue and write your own in a subclass, okay?

So like, for the number +44 20 87712924 this might hand back [qw(valid allocated geographic)]. Cute, right? 💖

✨ format

Returns a sanely formatted, E.123-compliant version of the number, complete with its IDD code. So for the UK number (0208) 771-2924 it would give you +44 20 8771 2924. Iconic. 🌈

The superclass implementation returns undef, which is nonsense, so like… always implement this one. No cap.

💅 format_using

Want something other than E.123? Pass this the name of the formatter you want instead.

So if you're in your "just the digits, ma'am" era, you use the Raw formatter like this:

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. So don't do that. 🙈

🦋 format_for_country

Give this a country code (either a two-letter ISO one or a numeric prefix) and it returns the number all nicely formatted — either nationally-formatted if the number is in the same country, or as a nationally-preferred international number if it isn't. Internally it's using the National and NationallyPreferredIntl formatters to do its thing.

💀 Beware of the potential performance hit! Like, it's giving real work. Take that into account.

🌸 canonical_number

If this number is part of a national number plan that maps onto another country, then this returns an object representing the number it's mapped to. Otherwise? You just get your own object handed right back to you. 🫶

This is similar to — and lowkey more useful than — translates_to, which'll either give you an object for the canonical number or undef if the number is already canonical.

👑 country

The two-letter ISO country code for the country where the call is actually gonna terminate.

This is implemented in the superclass, so you'll only have to write your own version for countries where part of the number range is overlayed with another country. Niche but valid.

🚨 Exception: for the UK, return 'uk', not 'gb'. Periodt.

Specifically, the superclass implementation peeks at the class name and returns the last two-letter code it finds in there. So, 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

⭐ raw_number

Returns all the digits of the number, except any leading country code or national dialling prefix. It's exactly equivalent to the area code (if such a thing even exists for that country) and the subscriber number, just concatenated together. Simple, clean, no notes. ✨

💀 translates_to

DEPRECATED

If the number forwards to another number (like a special rate number forwarding to a geographic one), or if it's part of a chunk of number-space mapped onto another chunk of number-space — like when a country has a shortcut to (part of) another country's number-space, an example being how Northern Ireland shows up as an area code in the Irish republic's numbering plan as well as being canonically an area code in the UK's numbering plan — then this method may return an object representing the target number. Otherwise it returns undef.

The superclass implementation returns undef, and it was never implemented for any of the country-specific subclasses bundled with Number::Phone. You're encouraged to not implement this in subclasses, and users should be using canonical_number instead. It's giving legacy, bestie. Move on. 🧚

🌈 DATA SOURCES 🙌

🍓 data_source

Class method — returns some hopefully useful text about the source of the data (if there even is any) that drives a country-specific module. The base class's implementation returns undef, because the base class itself has no data source. Fitting, honestly.

💜 libphonenumber_tag

Class method that you should not over-ride — it's implemented in the base class. It 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 it may occasionally be a little ahead of the most recent libphonenumber release, since the tag gets created before their release is built.

The current version of this is also documented over 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 you how to dial from the number represented by the invocant to the number represented by the argument. Group chat for phone numbers, basically.

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

(and yes bestie, that one is listed twice in the og docs, we're keeping it 💅)

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 help it out. The algorithm goes like this:

🌍 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. And if it dies, that means "I don't know how to dial this number". 😭

The superclass implementation's whole personality is just dying, bestie.

👀 Note that the meaning of undef is a bit different for this method. Careful with that.

Why die by default? Because some countries have genuinely weird arrangements for dialling some numbers domestically. In fact, both of the countries the author is most familiar with do, so the assumption is that others do too. It's giving chaos, but that's numbering plans for you. 💀

💅 CONSTRUCTOR 💅

new

Can be called with either one or two parameters. The first is an optional country code (check 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 gets 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 already, and looking the country up using Number::Phone::Country. That gives us a two-letter country code, which we use to try to load the right module. Then we pass the number through to that module's constructor and return whatever it says (which may be undef, if you passed in an invalid number — see SUBCLASSING below, bestie).

The constructor returns undef if it can't figure out what country you're even 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 that goes against this should document it.

If you call it with two parameters, then the two must match. So like, if you do this:

Number::Phone->new("FR", "+441424220001")

you'll get undef back, because while the number is valid… it ain't French, babes. 🇫🇷🙅

This usually applies when a single country's number plan contains other jurisdictions — the classic case being Guernsey, Jersey and the Isle of Man all 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, though, 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')

Convenient? Yes. Slightly cursed? Also yes. 🫶

🛠️ 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, pls and thank you!) 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 it 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 the exception, using UK instead of the ISO-mandated GB. (Main character behaviour, honestly. 👑)

NANP countries are also an exception, going like Number::Phone::NANP::XX.

📬 UPDATES 📬

Updates drop approximately every three months, including new data. 🗓️✨

There will also be intercalary releases to fix serious bugs in the code, and when large data updates (eg when a country's numbering scheme changes) get brought to the author's attention.

A release will not normally happen just because a country has added some new number range. So if that irks you… a discussion would be welcomed 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. So close, and yet so far. 🫠

🐛 BUGS/FEEDBACK 💅

okay bestie, if you find a bug — and like, no shade, bugs happen, it's giving software — pls tell the maintainer!! 🫶 Report them at:

https://github.com/DrHyde/perl-modules-Number-Phone/issues

and like, if you can, pls include a test case. genuinely iconic of you if you do ✨ a test case makes the whole thing a million times easier to fix, no cap.

📬 MAILING LIST 🌸

there's a mailing list for announcements, discussion and help!! basically the group chat of this module fr fr. Subscribe at:

https://groups.google.com/g/number-phone

come join us, it's lowkey wholesome 💖

👀 SEE ALSO 🌈

📦 SOURCE CODE REPOSITORY ⭐

get the code, clone it, live in it:

git://github.com/DrHyde/perl-modules-Number-Phone.git

Copyright 2004 - 2026 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.

so like — pick your licence, either one, dealer's choice 💅 both are literally right there in those files. free as in speech, bestie 🌈

🛸 CONSPIRACY 🧚

This module is also free-as-in-mason software.

...and that's all it says about that 🙈 i'm just the messenger. make of that what you will, bestie 💜

and that's a wrap on the whole page, angel 💖 this was Number::Phone(3pm), from perl v5.40.1, dated 2026-06-11 — go forth and phone-number responsibly, you absolute icon 👑✨

📦 where this page comes from