Skip to main content

​
Overview

The AsYouTypeFormatter class provides real-time formatting of phone numbers as they are entered, digit by digit. This is particularly useful for creating user-friendly input fields that automatically format phone numbers while users type.
The AsYouTypeFormatter should be obtained from PhoneNumberUtil::getAsYouTypeFormatter() rather than instantiating it directly.

​
Getting an Instance

To use the AsYouTypeFormatter, obtain an instance through PhoneNumberUtil: 
$phoneNumberUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$formatter = $phoneNumberUtil->getAsYouTypeFormatter('US');
​
regionCode
string
required
The country/region code where the phone number is being entered (e.g., ‘US’, ‘GB’, ‘DE’)

​
Methods

​
inputDigit()

Formats a phone number on-the-fly as each digit is entered. 
public function inputDigit(string $nextChar): string
​
nextChar
string
required
The most recently entered digit of a phone number. Formatting characters are allowed, but as soon as they are encountered, this method formats the number as entered and not “as you type” anymore. Full width digits and Arabic-Indic digits are allowed and will be shown as they are.
Returns: string - The partially formatted phone number

​
Example: Progressive Formatting

1

Create the formatter

Get an instance of AsYouTypeFormatter for your target region:
$phoneNumberUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$formatter = $phoneNumberUtil->getAsYouTypeFormatter('GB');
2

Input digits one by one

Call inputDigit() for each character the user enters:
echo $formatter->inputDigit('0'); // "0"
echo $formatter->inputDigit('1'); // "01"
echo $formatter->inputDigit('1'); // "011"
echo $formatter->inputDigit('7'); // "0117"
echo $formatter->inputDigit('4'); // "0117 4"
echo $formatter->inputDigit('9'); // "0117 49"
echo $formatter->inputDigit('6'); // "0117 496"
echo $formatter->inputDigit('0'); // "0117 496 0"
echo $formatter->inputDigit('1'); // "0117 496 01"
echo $formatter->inputDigit('2'); // "01174 96012"
echo $formatter->inputDigit('3'); // "0117 496 0123"
3

Display the formatted result

The formatter automatically applies the appropriate formatting based on the region and number pattern.

​
clear()

Clears the internal state of the formatter so it can be reused for formatting another number. 
public function clear(): void
Always call clear() before formatting a new phone number to ensure the formatter starts with a clean state.

​
Example: Reusing the Formatter

$phoneNumberUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$formatter = $phoneNumberUtil->getAsYouTypeFormatter('US');

// Format first number
foreach (str_split('2015551234') as $digit) {
    $result = $formatter->inputDigit($digit);
}
echo $result; // "(201) 555-1234"

// Clear and format second number
$formatter->clear();
foreach (str_split('4155552345') as $digit) {
    $result = $formatter->inputDigit($digit);
}
echo $result; // "(415) 555-2345"

​
inputDigitAndRememberPosition()

Same as inputDigit(), but remembers the position where the character is inserted. This is useful for maintaining cursor position in text inputs. 
public function inputDigitAndRememberPosition(string $nextChar): string
​
nextChar
string
required
The most recently entered digit of a phone number
Returns: string - The partially formatted phone number The remembered position can be retrieved later using getRememberedPosition() and will be automatically adjusted if additional formatting characters are inserted or removed.

​
getRememberedPosition()

Returns the current position in the partially formatted phone number of the character that was previously passed to inputDigitAndRememberPosition(). 
public function getRememberedPosition(): int
Returns: int - The position in the formatted string

​
Complete Usage Example

<?php
use libphonenumber\PhoneNumberUtil;

$phoneNumberUtil = PhoneNumberUtil::getInstance();
$formatter = $phoneNumberUtil->getAsYouTypeFormatter('GB');

$digits = '01174960123';
foreach (str_split($digits) as $digit) {
    $formatted = $formatter->inputDigit($digit);
    echo $formatted . "\n";
}
// Output progression:
// 0
// 01
// 011
// 0117
// 0117 4
// 0117 49
// 0117 496
// 0117 496 0
// 0117 496 01
// 01174 96012
// 0117 496 0123

​
Use Cases

​
Form Input Validation

Ideal for enhancing user experience in phone number input fields: 
// In your form handler
$userInput = $_POST['phone'];
$formatter = $phoneNumberUtil->getAsYouTypeFormatter('US');

foreach (str_split($userInput) as $char) {
    $formatted = $formatter->inputDigit($char);
}

// Display formatted number back to user
echo $formatted;

​
Real-time JavaScript Integration

Use with AJAX to format numbers as users type: 
// api/format-digit.php
$digit = $_GET['digit'];
$currentInput = $_GET['current'];

$formatter = $phoneNumberUtil->getAsYouTypeFormatter('US');

// Replay all digits
foreach (str_split($currentInput . $digit) as $d) {
    $result = $formatter->inputDigit($d);
}

header('Content-Type: application/json');
echo json_encode(['formatted' => $result]);

​
Important Notes

The formatter assumes input consists of digits and the plus sign only. Other formatting characters (spaces, dashes, parentheses) will cause the formatter to stop applying automatic formatting and return the input as entered.
  • The formatter intelligently detects international dialing prefixes (IDD) and country codes
  • National prefixes are automatically handled based on the region
  • Formatting patterns are selected based on the leading digits entered
  • Full-width digits and Arabic-Indic digits are supported and normalized
  • The formatter maintains state across multiple inputDigit() calls
  • Use clear() to reset the formatter for a new number

Build docs developers (and LLMs) love

Get started for freeTalk to us