smaccoun / PhoneNumberKit

A Swift framework for parsing, formatting and validating international phone numbers. Inspired by Google's libphonenumber.

PhoneNumberKit

Swift 5.0 framework for parsing, formatting and validating international phone numbers. Inspired by Google's libphonenumber.

Migrating from PhoneNumberKit 0.x? See the migration guide.

Features

	Features
☎️	Validate, normalize and extract the elements of any phone number string.
💯	Simple Swift syntax and a lightweight readable codebase.
🏁	Fast. 1000 parses -> ~0.4 seconds.
📚	Best-in-class metadata from Google's libPhoneNumber project.
🏆	Fully tested to match the accuracy of Google's JavaScript implementation of libPhoneNumber.
📱	Built for iOS. Automatically grabs the default region code from the phone.
📝	Editable (!) AsYouType formatter for UITextField.
🇺🇸	Convert country codes to country names and vice versa

Usage

Import PhoneNumberKit at the top of the Swift file that will interact with a phone number.

import PhoneNumberKit

All of your interactions with PhoneNumberKit happen through a PhoneNumberKit object. The first step you should take is to allocate one.

A PhoneNumberKit instance is relatively expensive to allocate (it parses the metadata and keeps it in memory for the object's lifecycle), you should try and make sure PhoneNumberKit is allocated once and deallocated when no longer needed.

let phoneNumberKit = PhoneNumberKit()

To parse a string, use the parse function. The region code is automatically computed but can be overridden if needed. PhoneNumberKit automatically does a hard type validation to ensure that the object created is valid, this can be quite costly performance-wise and can be turned off if needed.

do {
    let phoneNumber = try phoneNumberKit.parse("[phone]")
    let phoneNumberCustomDefaultRegion = try phoneNumberKit.parse("[phone]", withRegion: "GB", ignoreType: true)
}
catch {
    print("Generic parser error")
}

If you need to parse and validate a large amount of numbers at once, PhoneNumberKit has a special, lightning fast array parsing function. The default region code is automatically computed but can be overridden if needed. Here you can also ignore hard type validation if it is not necessary. Invalid numbers are ignored in the resulting array.

let rawNumberArray = ["0291 12345678", "[phone]", "04134 1234", "09123 12345"]
let phoneNumbers = phoneNumberKit.parse(rawNumberArray)
let phoneNumbersCustomDefaultRegion = phoneNumberKit.parse(rawNumberArray, withRegion: "DE",  ignoreType: true)

PhoneNumber objects are immutable Swift structs with the following properties:

phoneNumber.numberString
phoneNumber.countryCode
phoneNumber.nationalNumber
phoneNumber.numberExtension
phoneNumber.type // e.g Mobile or Fixed

Formatting a PhoneNumber object into a string is also very easy

phoneNumberKit.format(phoneNumber, toType: .e164) // [phone]
phoneNumberKit.format(phoneNumber, toType: .international) // [phone]
phoneNumberKit.format(phoneNumber, toType: .national) // [phone]

To use the AsYouTypeFormatter, just replace your UITextField with a PhoneNumberTextField (if you are using Interface Builder make sure the module field is set to PhoneNumberKit).

PhoneNumberTextField automatically formats phone numbers and gives the user full editing capabilities. If you want to customize you can use the PartialFormatter directly. The default region code is automatically computed but can be overridden if needed.

let textField = PhoneNumberTextField()

PartialFormatter().formatPartial("[phone]") // [phone]

You can also query countries for a dialing code or the dialing code for a given country

phoneNumberKit.countries(withCode: 33)
phoneNumberKit.countryCode(for: "FR")

Setting up with Carthage

Carthage is a decentralized dependency manager that automates the process of adding frameworks to your Cocoa application.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate PhoneNumberKit into your Xcode project using Carthage, specify it in your Cartfile:

github "marmelroy/PhoneNumberKit"

Setting up with CocoaPods

source 'https://github.com/CocoaPods/Specs.git'
pod 'PhoneNumberKit', '~> 3.0'