Phonie¶ ↑

Parsing, validating and creating phone numbers

Install¶ ↑

You can install the phonie library as a gem

gem install phonie

Initializing¶ ↑

You can initialize a new phone object with the number, area code, country code and extension number

Phonie::Phone.new('5125486', '91', '385')

or

Phonie::Phone.new(number: '5125486', area_code: '91', country_code: '385', extension: '143')

Parsing¶ ↑

You can create a new phone object by parsing from a string. Phonie::Phone does it’s best to detect the country and area codes:

Phonie::Phone.parse '+385915125486'
Phonie::Phone.parse '00385915125486'

If the country or area code isn’t given in the string, you must set it, otherwise it doesn’t work:

Phonie::Phone.parse '091/512-5486', country_code: '385'
Phonie::Phone.parse '(091) 512 5486', country_code: '385'

If you feel that it’s tedious, set the default country code once (in your config/environment.rb):

Phonie.configuration.default_country_code = '385'
Phonie::Phone.parse '091/512-5486'
Phonie::Phone.parse '(091) 512 5486'

Same goes for the area code:

Phonie::Phone.parse '451-588', country_code: '385', area_code: '47'

Alternatively Phonie can be configured via a block

Phonie.configure do |config|
  config.default_country_code = '385'
  config.default_area_code = '47'
  config.add_custom_named_format :short, '%A/%n1-%n2'
end

Phonie::Phone.parse '451-588'

Automatic country and area code detection¶ ↑

Like it’s stated above, Phone does it’s best to automatically detect the country and area code while parsing. To do this, phone uses data stored in data/countries.yml.

Each country code can have a regular expression named area_code that describes how the area code for that particular country looks like.

Validating¶ ↑

Validating is very relaxed, basically it strips out everything that’s not a number or ‘+’ character:

Phonie::Phone.valid? 'blabla 091/512-5486 blabla'

Formatting¶ ↑

Formating is done via the format method. The method accepts a Symbol or a String.

When given a string, it interpolates the string with the following fields:

• %c - country_code (385)

• %a - area_code (91)

• %A - area_code with leading zero (091)

• %n - number (5125486)

• %f - first @@n1_length characters of number (configured through Phonie.n1_length), default is 3 (512)

• %l - last characters of number (5486)

• %x - the extension number

• %X - the extension number with prefix

  pn = Phonie::Phone.parse('+385915125486')
  pn.to_s # => "+385915125486"
  pn.format("%A/%f-%l") # => "091/512-5486"
  pn.format("+ %c (%a) %n") # => "+ 385 (91) 5125486"
  

When given a symbol it is used as a lookup for the format in Phonie::Formatter.

pn.format(:europe) # => "+385 (0) 91 512 5486"
pn.format(:us) # => "(234) 123 4567"
pn.format(:default_with_extension) # => "+3851234567x143"

You can add your own custom named formats like so:

Phonie.configuration.add_custom_named_format :short, '%A/%n1-%n2'
pn.format(:short) # => 091/512-5486

ActiveModel validator¶ ↑

Phonie includes an ActiveModel validator. If you are using ActiveModel you can validate phone numbers like so:

class SomeModel
  include ActiveModel::Validations

  validates :phone_number, phone: true
end

model = SomeModel.new(phone_number: '')
model.valid? # false

model = SomeModel.new(phone_number: '+1 251 123 4567')
model.valid?  # true

Similarly you can validate if a number is a mobile number via:

validates :mobile_number, mobile_phone: true

Similarly you can validate if a number is in your default country via:

validates :mobile_number, default_country_phone: true

TODO¶ ↑

Add definitions for more countries

Currently tested on:

AE

UAE

AF

Afghanistan

AL

Albania

AM

Armenia

AR

Argentina

AT

Austria

AU

Australia

AZ

Azerbaijan

BA

Bosnia and Herzegovina

BD

Bangladesh

BE

Belgium

BF

Burkina Faso

BG

Bulgaria

BH

Bahrain

BO

Bolivia

BR

Brazil

BS

Bahamas

BT

Bhutan

BY

Belarus

BZ

Belize

CA

Canada

CH

Switzerland

CN

China

CR

Costa Rica

CU

Cuba

CY

Cyprus

CZ

Czech Republic

DE

Germany

DK

Denmark

DZ

Algeria

EC

Ecuador

EE

Estonia

EG

Egypt

ES

Spain

ET

Ethiopia

FI

Finland

FJ

Fiji

FR

France

GB

United Kingdom

GE

Georgia

GF

French Guiana

GH

Ghana

GP

Guadeloupe

GR

Greece

GT

Guatemala

GU

Guam

GY

Guyana

HK

Hong Kong

HR

Croatia

HU

Hungary

ID

Indonesia

IE

Ireland

IL

Israel

IN

India

IQ

Iraq

IR

Iran

IT

Italy

JM

Jamaica

JO

Jordan

JP

Japan

KE

Kenya

KR

South Korea

KW

Kuwait

LK

Sri Lanka

LT

Lithuania

LU

Luxembourg

LV

Latvia

MA

Morocco

ME

Montenegro

ML

Mali

MT

Malta

MX

Mexico

MY

Malaysia

NG

Nigeria

NI

Nicaragua

NL

Netherlands

NO

Norway

NP

Nepal

NZ

New Zealand

PA

Panama

PH

Philippines

PK

Pakistan

PT

Portugal

QA

Qatar

RS

Serbia

RU

Russian Federation

SA

Saudi Arabia

SC

Seychelles

SE

Sweden

SG

Singapore

SI

Slovenia

SK

Slovakia

SN

Senegal

SV

El Salvador

TO

Tonga

TT

Trinidad and Tobago

TW

Taiwan

TZ

Tanzania

UA

Ukraine

UG

Uganda

US

United States

UY

Uruguay

VE

Venezuela

VN

Vietnam

ZA

South Africa

ZW

Zimbabwe

How you can contribute¶ ↑

More testing is needed to add support for missing countries, and improve support for tested countries. In many cases only minimal testing is done on area codes, local number formats and number length where more exact matching is possible.

The best places to start is to read through the country tests and data/phone_countries.rb

Other libraries¶ ↑

This is based off a fork of the Phone gem (github.com/carr/phone), and was extensively modified for better support of country detection, and supports far more countries.

Contributors¶ ↑

Tomislav Carr, Don Morrison, Michael Squires, Todd Eichel (Fooala, Inc.), chipiga, Etienne Samson, Luke Randall, Wesley Moxam