libphonenumber for PHP

libphonenumber for PHP is a faithful port of Google’s libphonenumber, the de facto standard for handling international phone numbers. It parses raw number strings into structured PhoneNumber objects, validates them against per-region metadata, and formats them in E.164, national, international, and RFC3966 styles.

Beyond core parsing and validation, the library ships geocoding, carrier lookup, timezone mapping, short-number handling, and an as-you-type formatter. It tracks Google’s upstream metadata and version numbers, so PHP applications get the same country rules and edge-case coverage relied on across the ecosystem.

What You Get

• A PhoneNumberUtil singleton for parsing, validating, and formatting numbers in E.164, national, international, and RFC3966 formats
• Offline geocoding, carrier mapping, and timezone mapping keyed to Google’s bundled region metadata
• ShortNumberInfo for emergency and premium short codes, plus a PhoneNumberMatcher for extracting numbers from free text
• An AsYouTypeFormatter for live, character-by-character input formatting in forms and UIs
• Regularly regenerated metadata that follows Google’s upstream libphonenumber releases and version policy

Common Use Cases

• Validating and normalizing user-entered phone numbers at signup or checkout before storing them in E.164 form
• Displaying numbers in a locale-appropriate national or international format across a multi-country product
• Determining the region, carrier, or timezone of a number for routing, compliance, or analytics
• Formatting numbers as the user types in a web or mobile input field

Under The Hood

Architecture - The library centers on a PhoneNumberUtil singleton (src/PhoneNumberUtil.php, ~3,600 lines) that loads per-region PhoneMetadata from bundled data files via a MultiFileMetadataSourceImpl, parses input into immutable PhoneNumber value objects, and drives validation and formatting from that metadata. Specialized helpers (ShortNumberInfo, PhoneNumberOfflineGeocoder, PhoneNumberToCarrierMapper, PhoneNumberToTimeZonesMapper, AsYouTypeFormatter, PhoneNumberMatcher) sit alongside it and share the same metadata and prefix-mapper infrastructure.

Tech Stack - Pure PHP (8.1 through 8.5) with PSR-4 autoloading under the libphonenumber namespace and a hard dependency on the mbstring extension and giggsey/locale. Metadata is generated from Google’s upstream libphonenumber via build tooling in build/, and quality is enforced with PHPStan and Infection mutation testing configured in the repo.

Code Quality - The project carries an extensive PHPUnit suite under tests/ (PhoneNumberUtilTest, ShortNumberInfoTest, AsYouTypeFormatterTest, ExampleNumbersTest, and more) that exercises real example numbers per region, plus static analysis via phpstan.neon.dist and mutation testing via infection.json5. As a long-lived, widely depended-on port it is conservatively maintained and closely mirrors Google’s reference behavior.

API Design - The public API mirrors Google’s well-known libphonenumber surface: obtain the singleton with getInstance(), parse() into a PhoneNumber, then isValidNumber() and format() with PhoneNumberFormat constants. Per-purpose classes keep concerns separated, and seven dedicated docs pages plus README examples make common tasks discoverable, though the sheer breadth of the surface gives it a moderate learning curve.