kariha / tr-phone

v1.0.0 2026-09-22 22:32 UTC

Requires

• php: ^8.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.88
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.5 || ^11.5 || ^12.0

MIT

• Kariha Web Agency

• php
• validation
• mobile
• formatter
• phone
• telephone
• turkey
• phone-number
• Turkish
• gsm
• normalization
• Turkiye
• E164

Published on Packagist.org on 2026-09-22 23:04 UTC

README

English | Türkçe

TR Phone is a small, framework-agnostic PHP toolkit for Turkish phone number validation, Türkiye phone number normalization, +90 phone formatting, E.164 conversion, mobile number checks, and landline checks.

It is built for web forms, CRM systems, appointment software, e-commerce projects, WhatsApp integrations, customer databases, API payloads, and import cleanup jobs that need reliable Turkish phone handling without an external service.

What is TR Phone?

TR Phone focuses only on Türkiye / +90 numbers. It validates against Turkish numbering ranges documented by BTK and formats valid numbers consistently:

• E.164: [phone]
• National: 0555 000 00 00
• International: [phone]
• Compact national significant digits: 5550000000

The package runs locally. It does not call an API, does not use a database, and does not transmit phone-number data to Kariha or any third party.

Features

• Parse common Turkish phone number inputs such as 05550000000, 5550000000, [phone], 00905550000000, (0555) 000 00 00, and 0555-000-00-00
• Validate recognized Turkish mobile and geographic landline ranges
• Normalize to canonical 10-digit national significant numbers
• Format as E.164, national, international, or compact
• Distinguish mobile and landline numbers
• Return prefix-based original allocation metadata for mobile prefixes
• Throw meaningful exceptions or use safe tryParse() calls
• No Laravel, Symfony, database, HTTP, or external API dependency

Installation

composer require kariha/tr-phone

Quick Start

<?php

use Kariha\TrPhone\PhoneNumber;

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

echo $phone->e164();         // [phone]
echo $phone->national();     // 0555 000 00 00
echo $phone->international(); // [phone]
echo $phone->digits();       // 5550000000

Validation

use Kariha\TrPhone\PhoneNumber;

if (PhoneNumber::tryParse($input) !== null) {
    // The input is a recognized Turkish phone number.
}

You can also use the facade-style helper:

use Kariha\TrPhone\TrPhone;

if (TrPhone::validate('[phone]')) {
    // Valid Turkish phone number.
}

Normalization

use Kariha\TrPhone\TrPhone;

echo TrPhone::normalize('(0555) 000 00 00'); // 5550000000

TR Phone handles leading 0, +90, 0090, whitespace, parentheses, hyphens, dots, and pasted formatted values. It rejects unsupported international numbers instead of silently converting them.

Formatting

use Kariha\TrPhone\Format;
use Kariha\TrPhone\PhoneNumber;

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

echo $phone->format(Format::E164);          // [phone]
echo $phone->format(Format::NATIONAL);      // 0555 000 00 00
echo $phone->format(Format::INTERNATIONAL); // [phone]
echo $phone->format(Format::COMPACT);       // 5550000000

Mobile Numbers

$phone = PhoneNumber::parse('0532 123 45 67');

$phone->isMobile(); // true

Mobile validation is based on BTK mobile numbering ranges such as 50X, 53X, 54X, selected 55X, and other documented mobile-service prefixes.

BTK also lists special 5XX services under the mobile-number section, including mobile virtual network service numbers (510, 516, 561), call service numbers (512), M2M service numbers (570-575), GMPCS mobile satellite service numbers (592), and GSM-R railway communication service numbers (594). TR Phone treats these prefixes as valid Turkish mobile-numbering-plan entries, but does not describe them as ordinary consumer mobile operator allocations.

Landline Numbers

$phone = PhoneNumber::parse('0212 123 45 67');

$phone->isLandline(); // true
$phone->areaName();   // Istanbul Europe

Geographic numbers are recognized through BTK 2XX, 3XX, and 4XX area codes.

Prefix / Operator Information

$phone = PhoneNumber::parse('0532 123 45 67');

echo $phone->prefix();         // 532
echo $phone->prefixOperator(); // Turkcell
echo $phone->prefixService();  // Mobile electronic communication service

prefixOperator() and prefixAllocation() return prefix-based original allocation information. They do not identify the subscriber's current carrier. prefixService() describes the BTK service category for the prefix, which is especially useful for special services such as M2M, GMPCS, GSM-R, call service, and mobile virtual network service numbers.

Number Portability Warning

Türkiye supports mobile number portability. A mobile prefix may show the original allocation, but it is not proof of the current operator. Do not use this package for billing, routing, or carrier-sensitive decisions that require current network data.

Error Handling

use Kariha\TrPhone\Exception\InvalidPhoneNumberException;
use Kariha\TrPhone\PhoneNumber;

try {
    $phone = PhoneNumber::parse($input);
} catch (InvalidPhoneNumberException $exception) {
    // Show a user-friendly validation message or log the reason.
}

Use tryParse() when you prefer a non-throwing API:

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

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

Examples

More copy-paste examples are available in docs/examples.md.

API Reference

• PhoneNumber::parse(string $input): PhoneNumber
• PhoneNumber::tryParse(string $input): ?PhoneNumber
• PhoneNumber::isValidInput(string $input): bool
• PhoneNumber::digits(): string
• PhoneNumber::e164(): string
• PhoneNumber::national(): string
• PhoneNumber::international(): string
• PhoneNumber::format(Format|string $format): string
• PhoneNumber::isMobile(): bool
• PhoneNumber::isLandline(): bool
• PhoneNumber::prefix(): string
• PhoneNumber::prefixOperator(): ?string
• PhoneNumber::prefixAllocation(): ?string
• PhoneNumber::prefixService(): ?string
• PhoneNumber::areaName(): ?string
• TrPhone::validate(string $input): bool
• TrPhone::normalize(string $input): string
• TrPhone::format(string $input, Format|string $format = Format::E164): string

Laravel / Symfony / Plain PHP

TR Phone is plain PHP. Use it in Laravel, Symfony, Slim, Laminas, WordPress, custom PHP applications, queue jobs, import scripts, or any Composer-based project.

Requirements

• PHP 8.1 or higher
• Composer

Testing

composer install
composer test
composer analyse
composer cs
composer check

Data Source

Numbering data is maintained in src/Data/TurkishNumberingPlan.php and is based on BTK's public Turkish numbering plan pages, verified on 2026-09-23:

• https://www.btk.gov.tr/genel-numaralandirma-plani
• https://www.btk.gov.tr/ulusal-numaralandirma-plani

If BTK changes the plan, update the data file and add tests for the new ranges.

Contributing

Please read CONTRIBUTING.md. Do not post real customer phone numbers in issues; mask personal data such as 0555 *** ** 78.

Security

Please read SECURITY.md. Security reports can be sent to [e-mail].

License

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

About Kariha

Kariha Web Agency develops custom web software, hosting infrastructure, and digital solutions since 2003.

Website: https://www.kariha.net/

For commercial integrations or custom development: https://www.kariha.net/iletisim