phonelib

What phonelib does

Phonelib is a Ruby gem that validates and formats phone numbers. All of its validation logic is built on the data set from Google's libphonenumber library, which is the same data many applications use to decide whether a number is plausible for a given region. The gem can perform basic validation and can format a number into the E164 international format as well as into a national format that includes the national prefix. The README is candid that it does not yet include every feature of the underlying Google library, so it is a practical subset rather than a full reimplementation. The project has been written and tested on Rails 3.1 and later, which makes it a natural fit for Rails applications that need to store or display phone numbers correctly. With 1,163 stars and 142 forks, phonelib is one of the more established entries in this batch and is used in production by teams that want region aware phone handling without calling an external service. Because the gem relies on libphonenumber's metadata, behavior tracks that project closely, and the README points users to the original library's demo when a number parses differently than expected. That grounding in a widely trusted data source is the main reason the gem is popular for form validation and contact storage.

Configuration options

Phonelib exposes a set of global configuration switches that change how parsing and formatting behave. The most important is default_country, which accepts either a single ISO 3166-1 alpha-2 code such as CN or an array of codes such as CN and FR, used when a number does not include an explicit country prefix. For numbers that start with a plus sign, there is ignore_plus, which disables the country reset that would otherwise happen when the specified country does not match the number's own prefix. The parse_special switch enables parsing of special numbers like short codes and emergency numbers, and it is off by default. Vanity conversion, turned on with vanity_conversion, translates letters in a number to digits, so a value like 800-CALL-NOW becomes 800-225-5669. There is strict_check to disable sanitizing so that unexpected symbols cause the parse to fail, and strict_double_prefix_check to reject double prefixes. The extension separator used during formatting is configurable through extension_separator, while extension_separate_symbols controls which characters are treated as separators during parsing, accepting either a string of single characters or an array of multi character strings. These knobs let a team match local dialing habits. The options make the gem adaptable to regional numbering plans without changing application code, which is useful for forms that accept international input.

Installation and Rails integration

Adding phonelib to a project starts with the Gemfile, where the line gem 'phonelib' makes it available, followed by the bundle command to install. From there, configuration usually lives in an initializer at config/initializers/phonelib.rb so the defaults are set once at boot. The README shows examples such as setting Phonelib.default_country to a single country or to a list, and it documents each toggle with a short snippet. For Rails models, the gem can be used to build ActiveRecord validations, and the repository notes that a working example lives in the spec/dummy application shipped with the gem, which demonstrates phonelib based validation in practice. Bug reports go through the project's GitHub issues page, and the change log is kept on the releases page rather than in the README, so users should check there for version specific changes. The gem's focus stays on validation and formatting rather than on every feature of the upstream library, which keeps the surface small and the behavior predictable. When a number parses incorrectly, the README suggests checking the original libphonenumber demo first, and if the result matches, the issue belongs upstream with Google rather than with phonelib. If waiting is not an option, the gem offers Phonelib.add_additional_regex and Phonelib.additional_regexes to layer custom rules on top of the bundled data. With the MIT license, teams are free to use and modify it.

Editorial conclusion

Phonelib is distributed under the MIT license and carries 1,163 stars, and its validation is built directly on the data set from Google's libphonenumber library.