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

One-shot Formatting

Skip the explicit PhoneNumber instance when you just need a string:

Philiprehberger::Phone.format("4155551212", format: :e164, country: :us)
# => "+14155551212"

Philiprehberger::Phone.format("4155551212", format: :international, country: :us)
# => "+1 415 555 1212"

Accepted formats: :e164, :national, :international.

Validation

Philiprehberger::Phone.valid?("+44 20 7946 0958")  # => true
Philiprehberger::Phone.valid?("+1 555")             # => false

Country Detection

Phone.country_of returns the country symbol for a number (or nil) without raising:

Philiprehberger::Phone.country_of("+15551234567")               # => :us
Philiprehberger::Phone.country_of("020 7946 0958", country: :gb)  # => :gb
Philiprehberger::Phone.country_of("garbage")                    # => nil

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