philiprehberger-phone
Lightweight phone number parsing, validation, formatting, and metadata lookup for 36 countries
Requirements
- Ruby >= 3.1
Installation
Add to your Gemfile:
gem "philiprehberger-phone"
Or install directly:
gem install philiprehberger-phone
Usage
require "philiprehberger/phone"
phone = Philiprehberger::Phone.parse("+1 (555) 123-4567")
phone.valid? # => true
phone.country_code # => "1"
phone.national # => "5551234567"
phone.country # => :us
phone.e164 # => "+15551234567"
phone.formatted # => "(555) 123-4567"
phone.international # => "+1 (555) 123-4567"
phone.country_name # => "United States"
Country Hint
phone = Philiprehberger::Phone.parse("020 7946 0958", country: :gb)
phone.country_code # => "44"
phone.country # => :gb
Validation
Philiprehberger::Phone.valid?("+44 20 7946 0958") # => true
Philiprehberger::Phone.valid?("+1 555") # => false
Phone Type Detection
phone = Philiprehberger::Phone.parse("+18001234567")
phone.phone_type # => :toll_free
phone = Philiprehberger::Phone.parse("+447911123456")
phone.phone_type # => :mobile
phone = Philiprehberger::Phone.parse("+19001234567")
phone.phone_type # => :premium
phone = Philiprehberger::Phone.parse("+18001234567")
phone.toll_free? # => true
phone.mobile? # => false
Area Code Lookup
phone = Philiprehberger::Phone.parse("+12125551234")
phone.area_code_info # => { area_code: "212", region: "New York, NY" }
phone = Philiprehberger::Phone.parse("+442079460958")
phone.area_code_info # => { area_code: "20", region: "London" }
Vanity Number Conversion
Philiprehberger::Phone.vanity_to_digits("1-800-FLOWERS") # => "18003569377"
Philiprehberger::Phone.vanity_to_digits("1-800-COLLECT") # => "18002655328"
SMS Shortcode Validation
Philiprehberger::Phone.valid_shortcode?("12345", country: :us) # => true
Philiprehberger::Phone.valid_shortcode?("123456", country: :us) # => true
Philiprehberger::Phone.valid_shortcode?("1234", country: :us) # => false
Philiprehberger::Phone.valid_shortcode?("12345", country: :br) # => true
Philiprehberger::Phone.valid_shortcode?("1234", country: :kr) # => true
Supported shortcode countries: US, CA, GB, DE, FR, AU, IN, BR, MX, JP, KR, IT, ES.
Similar Comparison
a = Philiprehberger::Phone.parse("+1 (555) 123-4567")
b = Philiprehberger::Phone.parse("+1-555-123-4567")
a.similar_to?(b) # => true (same E.164: "+15551234567")
a == b # => true
c = Philiprehberger::Phone.parse("+44 20 7946 0958")
a.similar_to?(c) # => false
Carrier Identification
Carrier lookup is supported for US, CA, GB, and DE.
phone = Philiprehberger::Phone::PhoneNumber.new(country_code: "1", national: "2125551234", country: :us)
phone.carrier # => "AT&T"
phone = Philiprehberger::Phone::PhoneNumber.new(country_code: "1", national: "4161234567", country: :ca)
phone.carrier # => "Rogers"
Country Name
phone = Philiprehberger::Phone.parse("+15551234567")
phone.country_name # => "United States"
phone = Philiprehberger::Phone.parse("+442079460958")
phone.country_name # => "United Kingdom"
Masking
phone = Philiprehberger::Phone.parse("+15551234567")
phone.masked # => "+1******4567"
phone.masked(visible: 0) # => "+1**********"
phone.masked(visible: 99) # => "+15551234567"
Serialization
phone = Philiprehberger::Phone.parse("+15551234567")
phone.to_h
# => { country_code: "1", national: "5551234567", country: :us, ... }
Supported Countries
US, CA, GB, DE, FR, AU, JP, IN, BR, MX, ES, IT, NL, BE, CH, AT, SE, NO, DK, FI, PL, PT, IE, RU, CN, KR, SG, NZ, ZA, NG, KE, EG, AR, CL, CO, PE.
API
Philiprehberger::Phone
| Method | Description |
|---|---|
.parse(input, country: nil) |
Parse a phone number string into a PhoneNumber |
.valid?(input, country: nil) |
Check if a phone number is valid |
.vanity_to_digits(input) |
Convert vanity letters to digits (e.g. "1-800-FLOWERS") |
.valid_shortcode?(input, country: :us) |
Validate an SMS shortcode for a country |
Philiprehberger::Phone::PhoneNumber
| Method | Description |
|---|---|
#valid? |
Whether the number matches country length rules |
#country_code |
Numeric country calling code (e.g. "1", "44") |
#national |
National number digits only |
#e164 |
E.164 format ("+15551234567") |
#formatted |
Country-specific national format |
#international |
International format with country code |
#country |
Country symbol (e.g. :us, :gb) |
#phone_type |
Phone type: :mobile, :landline, :toll_free, :premium, :unknown |
#mobile? |
Whether the number is a mobile line |
#landline? |
Whether the number is a landline |
#toll_free? |
Whether the number is toll-free |
#premium? |
Whether the number is a premium-rate line |
#area_code_info |
Area code metadata { area_code:, region: } for US/CA/GB/DE |
#similar_to?(other) |
Whether two numbers have the same E.164 representation |
#country_name |
Human-readable country name (e.g. "United States") |
#carrier |
Carrier name based on prefix (US, CA, GB, DE) |
#masked(visible:) |
E.164 form with national digits masked as * except the last visible (default 4) |
#to_h |
Hash representation with all phone number attributes |
#inspect |
Human-readable debug string |
Development
bundle install
bundle exec rspec
bundle exec rubocop
Support
If you find this project useful: