Skip to main content

​
Overview

The PhoneNumberMatcher class finds and extracts telephone numbers from unstructured text. It implements the Iterator interface, allowing you to iterate over all phone numbers found in the text.
Vanity numbers (phone numbers using alphabetic digits such as ‘1-800-SIX-FLAGS’) are not currently supported.

​
Creating an Instance

Instances are created using PhoneNumberUtil::findNumbers(): 
$phoneNumberUtil = \libphonenumber\PhoneNumberUtil::getInstance();

$text = "Hi, can you ring me at 1430 on 0117 496 0123. Thanks!";

$phoneNumberMatcher = $phoneNumberUtil->findNumbers($text, 'GB');

​
Constructor Parameters

​
text
string
required
The text to search for phone numbers
​
country
string|null
required
The default country/region code to assume for phone numbers not written in international format. Use null or "ZZ" to only match numbers with a leading plus sign.
​
leniency
AbstractLeniency
default:"Leniency::VALID()"
The leniency level to use when evaluating candidate phone numbers. See Leniency Levels below.
​
maxTries
int
default:"65535"
The maximum number of invalid numbers to try before giving up. Must be >= 0. This helps avoid degenerate cases where text has many false positives.

​
Iteration Methods

Since PhoneNumberMatcher implements Iterator, you can use it in a foreach loop: 
foreach ($phoneNumberMatcher as $phoneNumberMatch) {
    var_dump($phoneNumberMatch->number());
    var_dump($phoneNumberMatch->rawString());
    var_dump($phoneNumberMatch->start());
    var_dump($phoneNumberMatch->end());
}

​
hasNext()

Check if there are more phone numbers to find. This method is part of the standard iterator interface accessed via valid(): 
while ($phoneNumberMatcher->valid()) {
    $match = $phoneNumberMatcher->current();
    // Process match
    $phoneNumberMatcher->next();
}
​
return
bool
Returns true if there are more matches available

​
next()

Advance to the next phone number match in the text: 
$phoneNumberMatcher->next();
This method moves the internal pointer to the next match and updates the state.

​
current()

Get the current phone number match: 
$match = $phoneNumberMatcher->current();
​
return
PhoneNumberMatch|null
Returns the current PhoneNumberMatch object, or null if no match is available

​
Leniency Levels

The leniency parameter controls how strict the matching should be. Four levels are available:

​
POSSIBLE

use libphonenumber\Leniency;

$matcher = $phoneUtil->findNumbers($text, 'US', Leniency::POSSIBLE());
The most permissive level. Matches any sequence of digits that could possibly be a phone number, with minimal validation. This may produce false positives. Use when: You want maximum recall and are willing to manually filter results.

​
VALID

$matcher = $phoneUtil->findNumbers($text, 'US', Leniency::VALID());
Matches phone numbers that pass validation checks. This is the default and recommended level for most use cases. Use when: You want a good balance between precision and recall.

​
STRICT_GROUPING

$matcher = $phoneUtil->findNumbers($text, 'US', Leniency::STRICT_GROUPING());
Matches valid phone numbers where the grouping of digits matches a known formatting pattern for the region. Use when: You want to avoid matching numbers that are formatted incorrectly for the region.

​
EXACT_GROUPING

$matcher = $phoneUtil->findNumbers($text, 'US', Leniency::EXACT_GROUPING());
The strictest level. Matches only phone numbers where the digit grouping exactly matches a standard formatting pattern, including all separators. Use when: You need the highest precision and only want perfectly formatted numbers.

​
Examples

​
Basic Phone Number Extraction

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();

$text = "Call me at +1 650-253-0000 or 0117 496 0123";
$matches = $phoneUtil->findNumbers($text, 'GB');

foreach ($matches as $match) {
    echo "Found: " . $match->rawString() . "\n";
    echo "Position: " . $match->start() . "-" . $match->end() . "\n";
    
    $number = $match->number();
    echo "Country: " . $number->getCountryCode() . "\n";
    echo "National: " . $number->getNationalNumber() . "\n";
}

​
Using Different Leniency Levels

use libphonenumber\Leniency;

// Find any possible phone numbers
$matcher = $phoneUtil->findNumbers(
    "Numbers: 555-1234, 123-4567",
    'US',
    Leniency::POSSIBLE()
);

// May find: 555-1234, 123-4567 (even if invalid)

​
Limiting Search Attempts

// Limit attempts to avoid processing text with many false positives
$text = "Random digits everywhere: 123 456 789 012 345 678 901 234";

$matcher = $phoneUtil->findNumbers(
    $text,
    'US',
    Leniency::VALID(),
    10  // Stop after 10 failed attempts
);

foreach ($matcher as $match) {
    echo "Found: " . $match->rawString() . "\n";
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us