carono/yii2-phone-helper

A helper for clearing a phone number and forming a string by mask

1.0.1 2025-07-31 18:12 UTC

Requires

• php: ^7.4 || 8.*
• yiisoft/yii2: ^2.0

MIT

• Alexander Kasyanov

• extension
• yii2

README

A Yii2 extension that provides helper functions for phone number processing, including normalization, validation, and formatting.

Features

• Phone number normalization (removing all non-digit characters)
• Phone number validation against country codes
• Formatting phone numbers according to masks
• Built-in validator for Yii2 models
• Comprehensive country code database included

Installation

The preferred way to install this extension is through composer.

Either run

composer require carono/yii2-phone-helper

or add

"carono/yii2-phone-helper": "*"

to the require section of your composer.json file.

Usage

Basic Phone Number Processing

use carono\yii2\helpers\PhoneHelper;

// Clear phone number from non-digit characters
$cleanNumber = PhoneHelper::clear('[phone]'); // returns '71234567890'

// Normalize phone number (returns null if number doesn't match any known country code)
$normalized = PhoneHelper::normalNumber('[phone]'); // returns '71234567890'

// Format phone number according to its country code mask
$formatted = PhoneHelper::asString('71234567890'); // returns '[phone]' for Russian numbers

Using in Yii2 Models

use carono\yii2\helpers\PhoneFilter;

public function rules()
{
    return [
        [['phone'], PhoneFilter::class],
        // or with custom validation
        [['phone'], 'filter', 'filter' => [PhoneHelper::class, 'normalNumber']],
    ];
}

Getting Country Code Information

$codeInfo = PhoneHelper::getCode('71234567890');
/*
Returns array like:
{
	"mask": "+7(###)###-##-##",
	"cc": "RU",
	"name_en": "Russia",
	"desc_en": "",
	"name_ru": "Россия",
	"desc_ru": ""
}
*/

Methods Reference

PhoneHelper class

• clear(string $number): string - Removes all non-digit characters from phone number
• normalNumber(string $number): ?string - Returns normalized number if valid, null otherwise
• asString(string $number, ?string $mask = null): string - Formats number according to mask
• getCode(string $number): ?array - Returns country code information for the number

PhoneFilter class

A Yii2 validator filter that automatically normalizes phone numbers in model attributes.

License

This extension is released under the MIT License. See the bundled LICENSE file for details.

Support

If you have any questions or issues, please create an issue on GitHub or contact the author at [e-mail].