dr-skot / phonenumberkit

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

PhoneNumberKit

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

🚧 PhoneNumberKit is currently beta software 🚧

| Remaining Objectives --- | --- ⚔ | Battle-test PhoneNumberKit in a major app (100k+ users).

Features

          |  Features

--------------------------|------------------------------------------------------------ :phone: | Validate, normalize and extract the elements of any phone number string. :100: | Simple Swift syntax and a lightweight readable codebase. :checkered_flag: | Fast. 1000 parses -> ~0.3 seconds. :books: | Best-in-class metadata from Google's libPhoneNumber project. :trophy: | Fully tested to match the accuracy of Google's JavaScript implementation of libPhoneNumber. :iphone: | Built for iOS. Automatically grabs the default region code from the phone. 📝 | Editable (!) AsYouType formatter for UITextField. :us: | 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

To parse and validate a string, initialize a PhoneNumber object and supply the string as the rawNumber. The region code is automatically computed but can be overridden if needed. In case of an error, it will throw and you can catch and respond to in your app's UI

do {
    let phoneNumber = try PhoneNumber(rawNumber:"[phone]")
    let phoneNumberCustomDefaultRegion = try PhoneNumber(rawNumber: "[phone]", region: "GB")
}
catch {
    print("Generic parser error")
}

If you need to parse and validate a large amount of numbers at once, there is a special function for that and it's lightning fast. The default region code is automatically computed but can be overridden if needed.

let rawNumberArray = ["0291 12345678", "[phone]", "04134 1234", "09123 12345"]
let phoneNumbers = PhoneNumberKit().parseMultiple(rawNumberArray)
let phoneNumbersCustomDefaultRegion = PhoneNumberKit().parseMultiple(rawNumberArray, region: "DE")

To use the AsYouTypeFormatter, just replace your UITextField with a PhoneNumberTextField.

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 dailing code for a given country

let phoneNumberKit = PhoneNumberKit()
phoneNumberKit.countriesForCode(33)
phoneNumberKit.codeForCountry("FR")

Formatting a parsed phone number to a string is also very easy

phoneNumber.toE164() // [phone]
phoneNumber.toInternational() // [phone]
phoneNumber.toNational() // [phone]

You can access the following properties of a PhoneNumber object

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

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', '~> 0.6'