Skip to content
This repository

Ruby library for phone number parsing, validation and formatting

branch: master


Parsing, validating and creating phone numbers


This documentation is for the unreleased development branch. The current stable version is 1.2.3


TODO: Description


Automatic country and area code detection

Phone does its best to automatically detect the country and area code while parsing. To do this, phone uses data stored in data/phone/countries.yml.

Each country code can have a regular expression named area_code that describes what the area code for that particular country looks like.

If an area_code regular expression isn't specified, the default, Phoner::Phone::DEFAULT_AREA_CODE (correct for the US) is used.


Validating is very relaxed, basically it strips out everything that's not a number or '+' character:

Phoner::Phone.valid? 'blabla 091/512-5486 blabla'


Formating is done via the #format method. The method accepts a Symbol or a String.

When given a string, it interpolates the string with the following fields:

  • %c - country_code (385)
  • %a - area_code (91)
  • %A - area_code with leading zero (091)
  • %n - number (5125486)
  • %f - first @@n1_length characters of number (configured through Phoner::Phone.n1_length), default is 3 (512)
  • %l - last characters of number (5486)
  • %x - the extension number
pn = Phoner::Phone.parse('+385915125486')
pn.to_s # => "+385915125486"
pn.format("%A/%f-%l") # => "091/512-5486"
pn.format("+ %c (%a) %n") # => "+ 385 (91) 5125486"

When given a symbol it is used as a lookup for the format in the Phoner::Phone.named_formats hash.

pn.format(:europe) # => "+385 (0) 91 512 5486"
pn.format(:us) # => "(234) 123 4567"
pn.format(:default_with_extension) # => "+3851234567x143"

You can add your own custom named formats like so:

Phoner::Phone.named_formats[:short] = '%A/%n1-%n2'
pn.format(:short) # => 091/512-5486

Finding countries by their isocode

If you don't have the country code, but you know from other sources what country a phone is from, you can retrieve the country using the country isocode (such as 'de', 'es', 'us', ...). Remember to call Phoner::Country.load before using this lookup.

if country = Phoner::Country.find_by_country_isocode(user_country_isocode)
  phone_number = Phoner::Phone.parse(user_input, :country_code => country.country_code)


require 'phone'


Initialize a new phone object with the number, area code, country code and extension number:'5125486', '91', '385') => '5125486', :area_code => '91', :country_code => '385', :extension => '143')


Create a new phone object by parsing from a string. Phoner::Phone does it's best to detect the country and area codes:

Phoner::Phone.parse '+385915125486'
Phoner::Phone.parse '00385915125486'

If the country or area code isn't given in the string, you must set it, otherwise it doesn't work:

Phoner::Phone.parse '091/512-5486', :country_code => '385'
Phoner::Phone.parse '(091) 512 5486', :country_code => '385'

If you feel that it's tedious, set the default country code once:

Phoner::Phone.default_country_code = '385'
Phoner::Phone.parse '091/512-5486'
Phoner::Phone.parse '(091) 512 5486'

Same goes for the area code:

Phoner::Phone.parse '451-588', :country_code => '385', :area_code => '47'


Phoner::Phone.default_country_code = '385'
Phoner::Phone.default_area_code = '47'

Phoner::Phone.parse '451-588'

Test Countries

  • [AU] Australia
  • [BA] Bosnia and Herzegovina
  • [BE] Belgium
  • [DE] Germany
  • [ES] Spain
  • [FR] France
  • [GB] United Kingdom
  • [HR] Croatia
  • [HU] Hungary
  • [IE] Ireland
  • [NL] Netherlands
  • [NZ] New Zealand
  • [RS] Serbia
  • [SE] Sweden
  • [SI] Slovenia
  • [UA] Ukraine
  • [US] United States
  • [ZA] South Africa

Known issues

There's an issue with Germany and Spanish area codes.



$ gem install phone

Or as a Rails plugin

$ script/plugin install git://


Copyright (c) 2010-2013 Tomislav Car, Infinum Copyright (c) 2013 Don Morrison

See {file:LICENSE.txt} for details.


Don Morrison, Michael Squires, Todd Eichel (Fooala, Inc.), chipiga, Etienne Samson, Luke Randall, Jakob Hilden, Tieg Zaharia

Something went wrong with that request. Please try again.