Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ianks/mini_phone
A fast phone number parser, validator and formatter for Ruby. This gem binds to Google's C++ libphonenumber for spec-compliance and performance.
https://github.com/ianks/mini_phone
libphonenumber phone phone-number phonelib phonenumber ruby telephone
Last synced: 8 days ago
JSON representation
A fast phone number parser, validator and formatter for Ruby. This gem binds to Google's C++ libphonenumber for spec-compliance and performance.
- Host: GitHub
- URL: https://github.com/ianks/mini_phone
- Owner: ianks
- License: mit
- Created: 2020-12-24T06:33:23.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2023-11-17T05:24:02.000Z (12 months ago)
- Last Synced: 2024-10-23T03:32:48.093Z (15 days ago)
- Topics: libphonenumber, phone, phone-number, phonelib, phonenumber, ruby, telephone
- Language: C++
- Homepage:
- Size: 154 KB
- Stars: 159
- Watchers: 1
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# MiniPhone
A Ruby gem which plugs directly into Google's native C++
[libphonenumber](https://github.com/google/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.
## Usage
### Checking if a phone number is valid
```ruby
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
```ruby
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
```ruby
phone_number = MiniPhone.parse('-12')
phone_number.possible? # false
```
### Getting the type of a phone number
```ruby
MiniPhone.parse('+12423570000').type # :mobile
MiniPhone.parse('+12423651234').type # :fixed_line
```
The possible types are directly mapped from [this
enum](https://github.com/google/libphonenumber/blob/4e9954edea7cf263532c5dd3861a801104c3f012/cpp/src/phonenumbers/phonenumberutil.h#L91):
```ruby
: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](https://github.com/daddyz/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.
## Benchmarks
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
```
## Installation
1. Install libphonenumber
```sh
brew install libphonenumber # mac
```
```sh
apt-get install -y libphonenumber-dev # debian / ubuntu
```
2. Add this line to your application's Gemfile:
```ruby
gem 'mini_phone'
```
3. And then execute:
```sh
bundle install
```
Or install it yourself as:
```sh
gem install mini_phone
```
### Installation on Heroku
1. In addition to the steps above add the [apt buildpack](https://github.com/heroku/heroku-buildpack-apt) to your Heroku app:
```sh
heroku buildpacks:add --index 1 heroku-community/apt
```
2. Create Aptfile in your repo with the following content:
```
libphonenumber-dev
```
## Development
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](https://rubygems.org).
## Contributing
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](https://github.com/ianks/mini_phone/blob/master/CODE_OF_CONDUCT.md).
## License
The gem is available as open source under the terms of the [MIT
License](https://opensource.org/licenses/MIT).
## 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](https://github.com/ianks/mini_phone/blob/master/CODE_OF_CONDUCT.md).