README

Laravel Phone Number Package based on the libphonenumber for PHP (Lite). It is a simple Laravel package for validating, formatting, and parsing phone numbers based on the PHP port of Google’s libphonenumber library, providing robust support for international phone number handling.

Installation

You can install the package via composer using the following command. The command will install the latest applicable version of the package.

composer require devsarfo/laraphone

You can publish the config file with:

php artisan vendor:publish --tag="laraphone-config"

Optionally, you can publish the translations with :

php artisan vendor:publish --tag="laraphone-translations"

Usage

Use the phone keyword in your validation rules array or use the DevSarfo\LaraPhone\Rules\PhoneNumberRule rule class to define the rule in an expressive way.

To put constraints on the allowed originating countries, you can explicitly specify the allowed country codes.

'phone' => 'phone:NO,GH',
// 'phone' => new PhoneNumberRule(['NO', 'GH'])

You can pass the country code from another field in the request. For example, to require a phone number to match the user's country.

'country_code' => 'required',
'phone' => ['required', new PhoneNumberRule($this->country_code)],

The country codes should be ISO 3166-1 alpha-2 compliant.

Validation Message

We provide validation for various cases out of the box. However, to enable the custom phone validation message, please add the following line to the validation.php language file in your resources/lang/{language}/ directory (e.g., resources/lang/en/validation.php):

'phone' => 'The :attribute field must be a valid phone number.',

PhoneNumber Utility class

You can use the DevSarfo\LaraPhone\Models\PhoneNumber class to handle various phone number operations, such as formatting, validating, and manipulating phone numbers. It provides an easy-to-use interface for working with phone numbers in different formats, and can be safely referenced in views or when saving to the database.

use DevSarfo\LaraPhone\Models\PhoneNumber;

(string) new PhoneNumber('+4722334455');    // +4722334455
(string) new PhoneNumber('22334455', 'NO'); // +4722334455

Alternatively you can use the phone() function found in the Helper.php. It returns a DevSarfo\LaraPhone\Models\PhoneNumber instance or the formatted string if $format was provided:

phone('+233244123456');             // PhoneNumber instance
phone('0244123456', 'GH');          // PhoneNumber instance
phone('0244123456', 'GH', $format); // string

Formatting

A PhoneNumber can be formatted in various ways:

$phone = new PhoneNumber('0244123456', 'GH');

$phone->format($format);       // See libphonenumber\PhoneNumberFormat
$phone->formatE164();          // +233244123456
$phone->formatInternational(); // +233 24 412 3456
$phone->formatRFC3966();       // tel:+233-24-412-3456
$phone->formatNational();      // 024 412 3456

Database

Store phone numbers in the E.164 format in your database. This format globally uniquely identifies a phone number, ensuring consistency and simplifying validation.

For example:

User input: 0244123456 (GH number)
Database storage: +233244123456

Why E.164 Format?

Consistency: E.164 format uniquely identifies a phone number globally.
Flexibility: You can format the number for display purposes (e.g., national or international formats).

Example Workflow:

User Input: 0244123456
Format to E.164: +233244123456
Save in Database: Store as +233244123456
Display: Format it as needed, e.g., 0244 123 456 for Ghana.

This ensures unique, globally recognizable phone numbers that can be displayed differently based on user needs.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

devsarfo / laraphone

Maintainers

Details