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"

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

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

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

phone = Philiprehberger::Phone::PhoneNumber.new(country_code: "1", national: "2125551234", country: :us)
phone.carrier  # => "AT&T"

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`
`#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
`#carrier`	Carrier name based on prefix (US only)
`#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:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT