百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
G

global_phone

> 编程语言
开源

在 Ruby 中使用 Google 的 libphonenumber 数据库解析、验证和格式化电话号码

548 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

在 Ruby 中使用 Google 的 libphonenumber 数据库解析、验证和格式化电话号码

GlobalPhone

GlobalPhone parses, validates, and formats local and international phone numbers according to the E.164 standard.

Store and display phone numbers in your app. Accept phone number input in national or international format. Convert phone numbers to international strings (+13125551212) for storage and retrieval. Present numbers in national format ((312) 555-1212) in your UI.

Designed with the future in mind. GlobalPhone uses format specifications from Google's open-source libphonenumber database. No need to upgrade the library when a new phone format is introduced—just generate a new copy of the database and check it into your app.

Pure Ruby. No dependencies. GlobalPhone is designed for Ruby 1.9.3 and up. (Works in 1.8.7, too—just bring your own json gem.)

Installation

  1. Add the global_phone gem to your app. For example, using Bundler:

     $ echo "gem 'global_phone'" >> Gemfile
     $ bundle install
    
  2. Use global_phone_dbgen to convert Google's libphonenumber PhoneNumberMetaData.xml file into a JSON database for GlobalPhone.

     $ gem install global_phone_dbgen
     $ global_phone_dbgen > db/global_phone.json
    
  3. Tell GlobalPhone where to find the database. For example, in a Rails app, create an initializer in config/initializers/global_phone.rb:

    ruby
    require 'global_phone'
    GlobalPhone.db_path = Rails.root.join('db/global_phone.json')

Examples

Parse an international number string into a GlobalPhone::Number object:

ruby
number = GlobalPhone.parse('+1-312-555-1212')
# => # national_string="3125551212">

Query the country code and likely territory name of the number:

ruby
number.country_code
# => "1"

number.territory.name
# => "US"

Present the number in national and international formats:

ruby
number.national_format
# => "(312) 555-1212"

number.international_format
# => "+1 312-555-1212"

Is the number valid? (Note: this is not definitive. For example, the number here is "valid" by format, but there are no US numbers that start with 555. The valid? method may return false positives, but should not return false negatives unless the database is out of date.)

ruby
number.valid?
# => true

Get the number's normalized E.164 international string:

ruby
number.international_string
# => "+13125551212"

Parse a number in national format for a given territory:

ruby
number = GlobalPhone.parse("(0) 20-7031-3000", :gb)
# => # national_string="2070313000">

Parse an international number using a territory's international dialing prefix:

ruby
number = GlobalPhone.parse("00 1 3125551212", :gb)
# => # national_string="3125551212">

Set the default territory to Great Britain (territory names are ISO 3166-1 Alpha-2 codes):

ruby
GlobalPhone.default_territory_name = :gb
# => :gb

GlobalPhone.parse("(0) 20-7031-3000")
# => # national_string="2070313000">

Shortcuts for validating a phone number:

ruby
GlobalPhone.validate("+1 312-555-1212")
# => true

GlobalPhone.validate("+442070313000")
# => true

GlobalPhone.validate("(0) 20-7031-3000")
# => false

GlobalPhone.validate("(0) 20-7031-3000", :gb)
# => true

Shortcuts for normalizing a phone number in E.164 format:

ruby
GlobalPhone.normalize("(312) 555-1212")
# => "+13125551212"

GlobalPhone.normalize("+442070313000")
# => "+442070313000"

GlobalPhone.normalize("(0) 20-7031-3000")
# => nil

GlobalPhone.normalize("(0) 20-7031-3000", :gb)
# => "+442070313000"

Caveats

GlobalPhone currently does not parse emergency numbers or SMS short code numbers.

Validation is not definitive and may return false positives, but should not return false negatives unless the database is out of date.

Territory heuristics are imprecise. Parsing a number will usually result in the territory being set to the primary territory of the region. For example, Canadian numbers will be parsed with a territory of US. (In most cases this does not matter, but if your application needs to perform geolocation using phone numbers, GlobalPhone may not be a good fit.)

Development

The GlobalPhone source code is hosted on GitHub. You can check out a copy of the latest code using Git:

$ git clone https://github.com/sstephenson/global_phone.git

If you've found a bug or have a question, please open an issue on the issue tracker. Or, clone the GlobalPhone repository, write a failing test case, fix the bug, and submit a pull request.

GlobalPhone is heavily inspired by Andreas Gal's PhoneNumber.js library.

Version History

1.0.1 (May 29, 2013)

  • GlobalPhone::Number#to_s returns the E.164 international string.
  • Ensure GlobalPhone::Number always returns strings for #national_format, #international_format, and #international_string, regardless of validity.
  • Relax format restrictions to more loosely match available national number patterns.

1.0.0 (May 28, 2013)

  • Initial public release.

License

Copyright © 2013 Sam Stephenson

Released under the MIT license. See LICENSE for details.

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Ruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言