Skip to content
Ruby library that parses a phone number and automatically formats it correctly, depending on the country/locale you set.
Find file
Pull request Compare This branch is 1 commit ahead, 39 commits behind habermann24:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



This is a library for representing phone numbers. It provides a PhoneNumber class that can format phone numbers depending on the region you set.



gem install phoney


git clone git://

Feature overview

  • Create phone number by parsing a string

    require 'phoney'
    # region defaults to US
    pn ="+17041234567")
    pn.to_s          # "+1 (704) 123-4567"
    pn.area_code     # "704"
    pn.country_code  # "1"
    pn.number        # "1234567"
  • Deals with many specific region formatting rules (e.g. DE)

    require 'phoney'
    PhoneNumber.default_region = :de
    pn ="04105456789")
    pn.to_s           # "+49 4105 456789"
    pn.area_code      # "4105"
    pn.country_code   # "49"
    pn.number         # "456789"

Creating PhoneNumber instances

Phoney gives you a PhoneNumber class that wraps all the logic of phone number parsing and representation. The default region phoney uses for formatting is the US-region format. So if you want to parse phone numbers from a different country, you have to set PhoneNumber.default_region or pass the region code every time!

PhoneNumber.default_region = :us

The most common way to create a PhoneNumber object is by parsing from a string:"7041231234")         # uses region :us"01805708090", :de)   # uses region :de

Or instead of parsing a string, you can provide a hash for the first parameter: => "1231234", :area_code => "704", :country_code => "1")

# falls back to US region, so also uses "1" for <tt>country_code</tt> => "1231234", :area_code => "704")


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)

  • %n - number (5125486)

    pn ='+446546546546')
    pn.to_s                     # => "+44 65 4654 6546"
    pn.format("%a/%n")          # => "64/46546546"
    pn.format("+ %c (%a) %n")   # => "+ 44 (65) 46546546"

Usually you will just want PhoneNumber to figure out how to format the number correctly. When given a symbol you can let the parser guess the best format and pass in one of the following auto-formatting symbols:

pn.format(:default) # => "+44 65 4654 6546"

# :national omits the country code and assumes a representation within the region
pn.format(:national) # => "65 4654 6546"

# :local even omits the area code and assumes a default area, so be careful!
pn.format(:local) # => "46 5465 46"


  • More test specs for different countries



Something went wrong with that request. Please try again.