nanayawkumi/gh-phone-validator

Laravel validation rule and helpers for Ghana phone numbers

v1.3.0 2025-12-29 15:27 UTC

Requires

• php: ^8.2
• illuminate/support: ^10.0|^11.0|^12.0
• illuminate/validation: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^9.0
• pestphp/pest: ^2.0

MIT

• Samuel Kumi-Buabeng

README

A Laravel validation rule and helper package for validating and normalizing Ghana phone numbers.

Installation

Install the package via Composer:

composer require nanayawkumi/gh-phone-validator

The package will automatically register its service provider if you're using Laravel's package auto-discovery.

Requirements

• PHP ^8.2
• Laravel ^10.0|^11.0|^12.0

Usage

Validation Rule

You can use the gh_phone validation rule in your form requests or controllers:

use Illuminate\Support\Facades\Validator;

$validator = Validator::make($request->all(), [
    'phone' => 'required|gh_phone',
]);

Or use the rule class directly:

use Nanayawkumi\GhPhoneValidator\Rules\GhPhone;

$validator = Validator::make($request->all(), [
    'phone' => ['required', new GhPhone()],
]);

Normalize Phone Numbers

The normalize() method converts various phone number formats to a standard 10-digit format (starting with 0):

use Nanayawkumi\GhPhoneValidator\GhPhoneValidator;

GhPhoneValidator::normalize('241234567');        // Returns: '0241234567'
GhPhoneValidator::normalize('[phone]');    // Returns: '0241234567'
GhPhoneValidator::normalize('233241234567');     // Returns: '0241234567'
GhPhoneValidator::normalize('024-123-4567');     // Returns: '0241234567'
GhPhoneValidator::normalize('024 123 4567');     // Returns: '0241234567'
GhPhoneValidator::normalize('invalid');          // Returns: null

Detect Network

The network() method identifies the network provider for a given phone number and returns a Network enum:

use Nanayawkumi\GhPhoneValidator\GhPhoneValidator;
use Nanayawkumi\GhPhoneValidator\Enums\Network;

$network = GhPhoneValidator::network('0241234567');
// Returns: Network::MTN

$network = GhPhoneValidator::network('0201234567');
// Returns: Network::TELECEL

$network = GhPhoneValidator::network('0261234567');
// Returns: Network::AIRTELTIGO

$network = GhPhoneValidator::network('invalid');
// Returns: null

For backward compatibility, you can also use networkInfo() to get the array format:

$network = GhPhoneValidator::networkInfo('0241234567');
// Returns: ['name' => 'MTN', 'slug' => 'mtn']

Validate Phone Numbers

The validate() method checks if a phone number is valid (10 digits and starts with a valid network prefix):

use Nanayawkumi\GhPhoneValidator\GhPhoneValidator;

GhPhoneValidator::validate('0241234567');  // Returns: true
GhPhoneValidator::validate('0201234567');  // Returns: true
GhPhoneValidator::validate('9991234567');  // Returns: false (invalid prefix)
GhPhoneValidator::validate('12345');       // Returns: false (invalid length)

Format Phone Numbers

The package provides several formatting methods to display phone numbers in different formats:

Raw Local Format

The formatRaw() method returns the phone number in raw local format (10 digits starting with 0):

use Nanayawkumi\GhPhoneValidator\GhPhoneValidator;

GhPhoneValidator::formatRaw('[phone]');  // Returns: '0241234567'
GhPhoneValidator::formatRaw('024 123 4567');   // Returns: '0241234567'
GhPhoneValidator::formatRaw('invalid');        // Returns: null

National Format

The formatNational() method formats the phone number with spaces for readability:

use Nanayawkumi\GhPhoneValidator\GhPhoneValidator;

GhPhoneValidator::formatNational('0241234567');     // Returns: '024 123 4567'
GhPhoneValidator::formatNational('[phone]');  // Returns: '024 123 4567'
GhPhoneValidator::formatNational('invalid');         // Returns: null

International Format

The formatInternational() method formats the phone number in international readable format:

use Nanayawkumi\GhPhoneValidator\GhPhoneValidator;

GhPhoneValidator::formatInternational('0241234567');     // Returns: '[phone]'
GhPhoneValidator::formatInternational('[phone]');  // Returns: '[phone]'
GhPhoneValidator::formatInternational('invalid');         // Returns: null

E.164 Format

The formatE164() method formats the phone number in E.164 international format:

use Nanayawkumi\GhPhoneValidator\GhPhoneValidator;

GhPhoneValidator::formatE164('0241234567');     // Returns: '[phone]'
GhPhoneValidator::formatE164('024 123 4567');   // Returns: '[phone]'
GhPhoneValidator::formatE164('invalid');        // Returns: null

Common Use Cases

UI Display

Format phone numbers for display in your user interface:

{{ $user->phone }}                    {{-- Raw format: 0241234567 --}}
{{ $user->phone->national() }}        {{-- National: 024 123 4567 --}}
{{ $user->phone->international() }}   {{-- International: [phone] --}}

SMS / Telco APIs

Format phone numbers in E.164 format for SMS gateways and telco APIs:

// Using the cast
$msisdn = $user->phone->e164();

// Or using the validator directly
$msisdn = GhPhoneValidator::formatE164($phone);

Eloquent Cast

This package provides an Eloquent cast for Ghana phone numbers.

Basic Usage

use Nanayawkumi\GhPhoneValidator\Casts\GhPhoneCast;

class User extends Model
{
    protected $casts = [
        'phone' => GhPhoneCast::class,
    ];
}

Behavior

• Accepts messy input when saving: The cast automatically normalizes various phone number formats (with spaces, dashes, international format, etc.) when saving to the database.

• Stores numbers in raw format by default: Phone numbers are stored in the database using the raw local format (e.g., 0241234567). You can optionally store in E.164 format using :e164.

• Works as string and value object: When retrieving the phone number, $user->phone works as a string (returns raw format) and also provides formatting methods:

// Direct string access (returns raw format)
echo $user->phone;                // Output: '0241234567'
$phone = $user->phone;            // String: '0241234567'

// Formatting methods
$user->phone->national();         // Returns: '024 123 4567'
$user->phone->international();   // Returns: '[phone]'
$user->phone->e164();            // Returns: '[phone]'
$user->phone->network();         // Returns: Network::MTN (enum)
$user->phone->raw();             // Returns: '0241234567'

Example:

// Saving with messy input
$user = new User();
$user->phone = '024 123 4567';  // Accepts various formats
$user->save();                   // Stored as '0241234567' (raw format)

// Retrieving and using
$user = User::find(1);

// Use as string (automatically returns raw format)
echo $user->phone;                    // Output: '0241234567'

// Use formatting methods
echo $user->phone->national();        // Output: '024 123 4567'
echo $user->phone->international();  // Output: '[phone]'
echo $user->phone->e164();           // Output: '[phone]'

Cast Storage Customization

You can control how phone numbers are stored in the database.

Store as Raw Local Format (default)

use Nanayawkumi\GhPhoneValidator\Casts\GhPhoneCast;

protected $casts = [
    'phone' => GhPhoneCast::class,
];

Phone numbers are stored in raw local format (e.g., 0241234567) by default.

Store as E.164 Format

use Nanayawkumi\GhPhoneValidator\Casts\GhPhoneCast;

protected $casts = [
    'phone' => GhPhoneCast::class . ':e164',
];

Phone numbers are stored in E.164 international format (e.g., [phone]).

Notes

• All formats are normalized before storage: Regardless of the input format (with spaces, dashes, international format, etc.), the phone number is normalized before being stored.

• Retrieval returns a value object that works as string: When retrieving from the database, you get a PhoneNumber value object that works as a string (returns raw format) and also provides formatting methods, regardless of how it was stored.

• Strict mode is respected: The cast respects the strict mode configuration when validating phone numbers before storage.

Example:

// Store as raw (default)
$user = new User();
$user->phone = '024 123 4567';
$user->save();  // Stored as '0241234567'

// Store as E.164 format
use Nanayawkumi\GhPhoneValidator\Casts\GhPhoneCast;

class User extends Model
{
    protected $casts = [
        'phone' => GhPhoneCast::class . ':e164',
    ];
}

$user = new User();
$user->phone = '024 123 4567';
$user->save();  // Stored as '[phone]'

// Retrieval works the same way regardless of storage format
$user = User::find(1);
echo $user->phone;                // Output: '0241234567' (always raw when used as string)
echo $user->phone->e164();        // Output: '[phone]'

Network Enum

The package provides a strongly-typed Network enum for working with network providers.

Using the Network Enum

use Nanayawkumi\GhPhoneValidator\GhPhoneValidator;
use Nanayawkumi\GhPhoneValidator\Enums\Network;

$network = GhPhoneValidator::network('0241234567');

if ($network === Network::MTN) {
    // Do something
}

$network->label(); // MTN
$network->slug();  // mtn

From Eloquent Cast

When using the Eloquent cast, the network() method returns a Network enum:

use Nanayawkumi\GhPhoneValidator\Enums\Network;

$user->phone->network(); // Network enum (Network::MTN, Network::TELECEL, etc.)

// Use it in conditionals
if ($user->phone->network() === Network::MTN) {
    // User is on MTN network
}

// Get network label
echo $user->phone->network()?->label(); // MTN

// Get network slug
echo $user->phone->network()?->slug();  // mtn

Available Methods

The Network enum provides the following methods:

• label() - Returns the human-readable network name (e.g., "MTN", "Telecel")
• slug() - Returns the network slug (e.g., "mtn", "telecel")
• codes() - Returns an array of network prefix codes
• fromPhone(string $phone) - Static method to get network from a phone number

Example:

use Nanayawkumi\GhPhoneValidator\Enums\Network;

$network = Network::fromPhone('0241234567');

if ($network) {
    echo $network->label();        // MTN
    echo $network->slug();        // mtn
    print_r($network->codes());    // ['024', '054', '055', ...]
}

Supported Networks

The package recognizes the following network providers:

• MTN: 024, 054, 055, 059, 025, 053, 023
• Telecel: 020, 050
• AirtelTigo: 026, 056, 027, 057

Configuration

Publish the configuration file to customize network settings:

php artisan vendor:publish --tag=gh-phone-validator-config

This will create a config/gh-phone-validator.php file where you can modify network codes and names.

Strict Mode

Strict mode controls whether the package accepts phone numbers with unknown network prefixes:

• Enabled (strict => true): Only accepts phone numbers with prefixes that match known network codes. Numbers with unknown prefixes will return null when normalized.
• Disabled (strict => false): Accepts any valid 10-digit Ghana phone number starting with 0, even if the prefix isn't in the known networks list.

// In config/gh-phone-validator.php
'strict' => true,  // Reject unknown prefixes
'strict' => false, // Accept any valid 10-digit number (default)

Example:

// With strict mode enabled
config()->set('gh-phone-validator.strict', true);
GhPhoneValidator::normalize('0291234567');  // Returns: null (unknown prefix)

// With strict mode disabled
config()->set('gh-phone-validator.strict', false);
GhPhoneValidator::normalize('0291234567');  // Returns: '0291234567' (accepted)

License

This package is open-sourced software licensed under the MIT license.

Author

Samuel Kumi-Buabeng