aariess/phone

phone

, _(*1)

Parsing, validating and creating phone numbers, _(*2)

• Homepage
• Issues
• Documentation
• [Email](mailto:don at elskwid.net)

Version

This documentation is for the unreleased development branch., _(*3)

• Current release: 1.3.0.beta1
• Current stable: 1.2.3

Description

Ruby library for phone number parsing, validation, and formatting., _(*4)

Features

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., _(*5)

Each country code can have a regular expression named area_code that describes what the area code for that particular country looks like., _(*6)

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

Validating

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

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

Formatting

Formating is done via the #format method. The method accepts a Symbol or a String., _(*9)

When given a string, it interpolates the string with the following fields:, _(*10)

• %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., _(*11)

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:, _(*12)

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., _(*13)

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

Examples

require 'phone'

Initializing

Initialize a new phone object with the number, area code, country code and extension number:, _(*14)

Phoner::Phone.new('5125486', '91', '385')

Phoner::Phone.new(:number => '5125486', :area_code => '91', :country_code => '385', :extension => '143')

Parsing

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

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:, _(*16)

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:, _(*17)

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

Same goes for the area code:, _(*18)

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

or, _(*19)

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., _(*20)

Requirements

Install

$ gem install phone

Or as a Rails plugin, _(*21)

$ script/plugin install git://github.com/carr/phone.git

Copyright

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

See LICENSE.txt for details., _(*23)

Contributors

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