Download the PHP package nanayawkumi/gh-phone-validator without Composer

Gh Phone Validator

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

Installation

Install the package via Composer:

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

Requirements

• PHP ^8.2 (Laravel 13 requires PHP ^8.3)
• Laravel ^10.0|^11.0|^12.0|^13.0

Usage

Validation Rule

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

Or use the rule class directly:

Normalize Phone Numbers

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

Detect Network

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

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

Validate Phone Numbers

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

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):

National Format

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

International Format

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

E.164 Format

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

Common Use Cases

UI Display

Format phone numbers for display in your user interface:

SMS / Telco APIs

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

Eloquent Cast

This package provides an Eloquent cast for Ghana phone numbers.

Basic Usage

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:

Example:

Cast Storage Customization

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

Store as Raw Local Format (default)

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

Store as E.164 Format

Phone numbers are stored in E.164 international format (e.g., +233241234567).

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:

Network Enum

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

Using the Network Enum

From Eloquent Cast

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

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:

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:

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.

Example:

License

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

Author

Samuel Kumi-Buabeng