Ruby library for phone number parsing, validation and formatting
Clone or download
carr Merge pull request #84 from gee-forr/master
Allow 06x area codes for ZA numbers
Latest commit 5abaf4b Mar 11, 2017


Beta Gem Version Gem Version Build Status Dependency Status Code Climate

Parsing, validating and creating phone numbers


This documentation is for the unreleased development branch.


Ruby library for phone number parsing, validation, and formatting.


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
  • [ME] Montenegro
  • [NL] Netherlands
  • [NZ] New Zealand
  • [PT] Portugal
  • [RS] Serbia
  • [SE] Sweden
  • [SI] Slovenia
  • [UA] Ukraine
  • [US] United States
  • [UY] Uruguay
  • [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 LICENSE.txt for details.


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