A Ruby gem which plugs directly into Google's native C++ libphonenumber for extremely fast and robust phone number parsing, validation, and formatting. On average, most methods are 70x to 80x faster than other Ruby phone number libraries.
Checking if a phone number is valid
MiniPhone.valid?('+14043841399') # true MiniPhone.valid_for_country?('(404) 384-1399', 'US') # true MiniPhone.valid_for_country?('(404) 384-1399', 'GB') # false
Formatting a number
MiniPhone.default_country = 'US' phone_number = MiniPhone.parse('404-384-1399') phone_number.e164 # +14043841399 phone_number.national # (404) 384-1399 phone_number.raw_national # 4043841399 phone_number.dasherized_national # 404-384-1399 phone_number.international # +1 404-384-1399 phone_number.rfc3966 # tel:+1-404-384-1384
Checking if a phone number is possible
phone_number = MiniPhone.parse('-12') phone_number.possible? # false
Getting the type of a phone number
MiniPhone.parse('+12423570000').type # :mobile MiniPhone.parse('+12423651234').type # :fixed_line
The possible types are directly mapped from this enum:
:fixed_line :mobile :fixed_line_or_mobile :toll_free :premium_rate :shared_cost :voip :personal_number :pager :uan :voicemail :unknown
Compatibility with PhoneLib
MiniPhone aims to be compatible with Phonelib. In many cases it can be a drop in replacement. It has a smaller feature set, so it is not a replacement for every use case. If there is a feature you need, open an issue and we will try to support it.
On average, most methods are 40x to 50x faster than other libraries. To run the benchmarks locally, execute:
bundle exec rake bench
Results from my Linux (5.10.6-arch1-10)
Comparison: MiniPhone: valid?: 33382.0 i/s Phonelib: valid?: 422.8 i/s - 78.95x (± 0.00) slower TelephoneNumber: valid?: 164.3 i/s - 203.13x (± 0.00) slower Comparison: MiniPhone: e164: 41187.5 i/s Phonelib: e164: 579.0 i/s - 71.14x (± 0.00) slower TelephoneNumber: e164: 228.8 i/s - 179.99x (± 0.00) slower
brew install libphonenumber # mac
apt-get install -y libphonenumber-dev # debian / ubuntu
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
gem install mini_phone
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake spec to run the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the
.gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/ianks/mini_phone. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the MiniPhone project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.