[Awesome Ruby Gem] Use telephone_number gem to validate phone number on Google's libphonenumber library

Posted on Edited on In , , Views: Word count in article: 5.3k Reading time ≈ 5 mins.

TelephoneNumber

TelephoneNumber is global phone number validation gem based on Google’s libphonenumber library google/libphonenumber: Google’s common Java, C++ and JavaScript library for parsing, formatting, and validating international phone numbers. - https://github.com/google/libphonenumber.

Demo

Feel free to check out our demo! Numberjack - http://numberjack.io/

Installation

You can install it as a gem:

1
$ gem install telephone_number

or add it into a Gemfile (Bundler):

1
2
3
4
5
# Gemfile

# mobi/telephone_number: Phone number validation for Ruby
# https://github.com/mobi/telephone_number
gem 'telephone_number', '1.4.12'

Usages

Rails Validation

1
validates :my_attribute_name, telephone_number: {country: proc{|record| record.country}, types: [:fixed_line, :mobile, etc]}

Valid Phone Types

  • :area_code_optional

  • :fixed_line

  • :mobile

  • :no_international_dialling

  • :pager

  • :personal_number

  • :premium_rate

  • :shared_cost

  • :toll_free

  • :uan

  • :voicemail

  • :voip

Country

In this example, record.country must yield a valid two letter country code such as :us, :ca or 'DE'
You can also just pass a String or Symbol instead of a Proc.

Manual Usage

You can obtain a TelephoneNumber object by calling:

1
2
3
4
5
6
7
phone_object = TelephoneNumber.parse("3175082237", :us) ==>

#<TelephoneNumber::Number:0x007fe3bc146cf0
  @country=:US,
  @e164_number="13175083348",
  @national_number="3175083348",
  @original_number="3175083348">

After that you have the following instance methods available to you.

valid_types

Returns all types that the number is considered valid for.

1
phone_object.valid_types ==> [:fixed_line, :mobile, :toll_free]

valid?

Returns boolean value indicating whether or not valid_types is empty.

1
phone_object.valid? ==> true

national_number(formatted: true)

Returns the national formatted number including special characters such as parenthesis and dashes. You can omit the special characters by passing formatted: false

1
phone_object.national_number ==> "(317) 508-2237"

international_number(formatted: true)

Returns the international formatted number including special characters such as parenthesis and dashes. You can omit the special characters by passing formatted: false

1
phone_object.international_number ==> "+1 317-508-2237"

e164_number(formatted: true)

Returns the international formatted number including special characters such as parenthesis and dashes. You can omit the special characters by passing formatted: false

1
phone_object.e164_number ==> "+13175082237"

country

Returns an object containing data related a the number’s country.

1
2
3
4
5
phone_object.country ===>
 #<TelephoneNumber::Country:0x007fb976267410
 @country_code="1",
 @country_id="US",
 ...

location

Returns the location of the number. Default locale is :en

1
2
3
phone_object.location ==> "Indiana"

phone_object.location(:ja) ==> "ソウル特別市"

timezone

Returns the time zone of the number.

1
phone_object.timezone ==> "America/New_York"

Class Methods

You also have the following class methods available to you.

parse

Returns a TelephoneNumber object.

1
TelephoneNumber.parse("3175082237", :US)

If you pass an E164 formatted number, we will determine the country on the fly.

1
TelephoneNumber.parse("+13175082237")

valid?

Returns boolean value indicating whether or not a particular number is valid.

1
TelephoneNumber.valid?("3175082237", :US) ==> true

If you are looking to validate against a specific set of keys, you can pass in an array of keys

1
2
TelephoneNumber.valid?("3175082237", :US, [:mobile, :fixed_line]) ==> true
TelephoneNumber.valid?("3175082237", :US, [:toll_free]) ==> false

invalid?

Returns boolean value indicating whether or not a particular number is invalid.

1
TelephoneNumber.invalid?("3175082237", :US) ==> false

If you are looking to invalidate against a specific set of keys, you can pass in an array of keys

1
2
TelephoneNumber.invalid?("3175082237", :US, [:mobile, :fixed_line]) ==> false
TelephoneNumber.invalid?("3175082237", :US, [:toll_free]) ==> true

Configuration

Override File

In the event that you need to override the data that Google is providing, you can do so by setting an override file. This file is expected to be in the same format as Google’s as well as serialized using Marshal.

To generate a serialized override file:

1
2
ruby bin/console
TelephoneNumber.generate_override_file("/path/to/file")

In this instance, /path/to/file represents an xml file that has your custom data in the same structure that Google’s data is in.

You can set the override file with:

1
TelephoneNumber.override_file = "/path/to_file.dat"

Default Number Pattern

If TelephoneNumber is passed an invalid number and then asked to format that number, it will simply return an unformatted string of the originally passed number. This is because formatting rules will not be found for invalid numbers. If this is unacceptable, you can set a default_format_pattern and default_format_string that TelephoneNumber will use attempt to format invalid numbers.

1
2
3
4
5
6
TelephoneNumber.default_format_pattern = "(\\d{3})(\\d{3})(\\d*)"
TelephoneNumber.default_format_string = "($1) $2-$3"

invalid_number = "1111111111"
phone_object = TelephoneNumber.parse(invalid_number, :US)
phone_object.national_number ==> "(111) 111-1111"

References

[1] mobi/telephone_number: Phone number validation for Ruby - https://github.com/mobi/telephone_number

[2] telephone_number | RubyGems.org | your community gem host - https://rubygems.org/gems/telephone_number/

[3] google/libphonenumber: Google’s common Java, C++ and JavaScript library for parsing, formatting, and validating international phone numbers. - https://github.com/google/libphonenumber

[4] Numberjack - http://numberjack.io/