aTR Phone: Turkish Phone Number Validation for PHP

TR Phone: Turkish Phone Number Validation and Normalization for PHP

Collecting a phone number in a web project may look simple, but different input formats can quickly become a problem once the data is stored and reused.

The same phone number can be entered in several different ways:

0555 000 00 00
5550000000
+90 555 000 00 00
0090 555 000 00 00
(0555) 000 00 00
0555-000-00-00

In CRM systems, appointment software, WhatsApp integrations, e-commerce projects and customer databases, this data needs to be stored in a consistent format.

To solve this need, we developed and released TR Phone as an open-source package.

TR Phone is a framework-independent PHP package designed to validate, normalize and format Turkish phone numbers into consistent standard formats.

What does TR Phone do?

The package parses Turkish phone numbers entered in different formats and converts them into a standardized structure.

For example:

use Kariha\TrPhone\PhoneNumber;

$phone = PhoneNumber::parse('0555 000 00 00');

echo $phone->e164();
// +905550000000

echo $phone->national();
// 0555 000 00 00

echo $phone->international();
// +90 555 000 00 00

echo $phone->digits();
// 5550000000

This allows applications to work with consistent phone number data regardless of which common input format the user enters.

TR Phone currently provides the following features:

• Validation of Turkish mobile and geographic landline numbers
• Support for numbers starting with 0, +90 and 0090
• E.164, national, international and compact output formats
• Mobile and landline detection
• Geographic area and city information for landline numbers
• Prefix allocation information for mobile numbers
• Identification of special 5XX services such as M2M, GMPCS, GSM-R and mobile virtual network services
• Safe rejection of invalid or unsupported phone numbers

No external API required

TR Phone runs entirely within PHP.

Phone numbers are not sent to an external API, no third-party validation service is used and the package does not require a database.

This makes it suitable for form validation, data cleanup and normalization directly inside the application.

Installation with Composer

The package can be installed directly from Packagist:

composer require kariha/tr-phone

A phone number received from a form can then be validated easily:

use Kariha\TrPhone\PhoneNumber;

$phone = PhoneNumber::tryParse($input);

if ($phone === null) {
    // Invalid or unsupported phone number
}

For simpler usage, the TrPhone helper class can also be used:

use Kariha\TrPhone\TrPhone;

if (TrPhone::validate('+90 532 123 45 67')) {
    // Valid Turkish phone number
}

$normalized = TrPhone::normalize('0532 123 45 67');
// 5321234567

Important note about mobile operator information

Because mobile number portability is available in Türkiye, a phone number prefix does not always indicate the subscriber's current operator.

For example, the 532 prefix was originally allocated to Turkcell, but the number may later have been transferred to another operator.

For this reason, TR Phone presents operator information as prefix-based allocation information rather than as the subscriber's current mobile operator.

BTK numbering plan

The Turkish numbering data included in the package is based on the General Numbering Plan and National Numbering Plan published by the Information and Communication Technologies Authority (BTK).

Supported area codes and prefixes are also covered by automated tests.

Framework independent

TR Phone only requires PHP and Composer.

It does not require Laravel, Symfony, WordPress or any other framework. It can be used in custom PHP applications as well as other Composer-based PHP projects.

The package is automatically tested on PHP 8.1, 8.2, 8.3 and 8.4 through GitHub Actions.

PHPUnit, PHPStan and PHP CS Fixer checks are also included in the development workflow.

Open source

TR Phone is released as open-source software under the MIT license.

You can review the source code, use it in your own projects, report issues or contribute improvement suggestions.

GitHub:
https://github.com/kariha-dev/tr-phone

Packagist:
https://packagist.org/packages/kariha/tr-phone

TR Phone was developed from a real data-standardization need we encountered in our own projects. We plan to keep the package up to date as the Turkish numbering plan evolves.