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
phone.e164          # => "+442079460958"

A national trunk 0 (used by most of Europe, Australia, and others) is dropped when composing the E.164 number. It is preserved for NANP (+1) and for plans where a leading 0 is significant.

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

Extracting Numbers from Text

Phone.extract scans free text and returns the valid numbers as PhoneNumber instances, deduped by E.164 and in order of first appearance. Dates, long digit runs, order numbers, decimals, and digits inside words or emails are skipped:

text = "Call (415) 555-1212 or +44 20 7946 0958. Again: 415.555.1212. Due 2026-10-30."
Philiprehberger::Phone.extract(text, country: :us).map(&:e164)
# => ["+14155551212", "+442079460958"]

The country: hint applies to numbers written without a + prefix.

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

The shared NANP +1 code is disambiguated between the US and Canada by the 3-digit area code, so Canadian numbers resolve to :ca (and get correct area-code and carrier lookups):

Philiprehberger::Phone.country_of("+14161234567")  # => :ca (Toronto)
Philiprehberger::Phone.country_of("+12125551234")  # => :us (New York)

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

PhoneNumber also implements eql? and hash (both keyed off E.164), so equal numbers dedupe in a Set and collapse as Hash keys regardless of formatting:

require "set"

a = Philiprehberger::Phone.parse("+1 (555) 123-4567")
b = Philiprehberger::Phone.parse("+1-555-123-4567")

Set.new([a, b]).size          # => 1
{ a => "primary" }[b]         # => "primary"

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"

tel: URIs

phone = Philiprehberger::Phone.parse("+14155551212")
phone.rfc3966  # => "tel:+1-415-555-1212"

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