devsarfo / laraphone
Laravel Phone Number Package based on the PHP port of libphonenumber by Google
Fund package maintenance!
Requires
- php: ^8.2
- giggsey/libphonenumber-for-php-lite: ^9.0.43
- illuminate/contracts: ^11.0|^12.0|^13.0
- illuminate/support: ^11.0|^12.0|^13.0
- illuminate/validation: ^11.0|^12.0|^13.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^2.9||^3.0
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.1.1
- orchestra/testbench: ^11.0||^10.0||^9.0
- pestphp/pest: ^4.0||^3.0
- pestphp/pest-plugin-arch: ^4.0||^3.0
- pestphp/pest-plugin-laravel: ^4.0||^3.0
- phpstan/extension-installer: ^1.3||^2.0
- phpstan/phpstan-deprecation-rules: ^1.1||^2.0
- phpstan/phpstan-phpunit: ^1.3||^2.0
- spatie/laravel-ray: ^1.35
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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
Validation messages are provided out of the box, e.g. "The phone must be a valid phone number for Ghana." Publish the translations to change them.
You can also override the message the usual Laravel ways. Custom messages may use the :country placeholder:
// Per validator Validator::make($data, ['phone' => 'phone:GH,NO'], [ 'phone.phone' => 'Enter a valid :country number.', ]); // Application-wide, in lang/{locale}/validation.php 'phone' => 'The :attribute field must be a valid phone number.',
An application-wide validation.phone line only replaces the generic message (no country given). Country-specific messages such as "…for Ghana." still come from the package unless you set an inline or validation.custom message.
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', PhoneFormat::NATIONAL); // string
Facade
The LaraPhone facade offers the same operations without creating objects yourself:
use DevSarfo\LaraPhone\Enums\PhoneFormat; use DevSarfo\LaraPhone\Facades\LaraPhone; LaraPhone::make('0244123456', 'GH'); // PhoneNumber instance LaraPhone::isValid('0244123456', 'GH'); // true LaraPhone::format('0244123456', 'GH'); // +233244123456 LaraPhone::format('0244123456', 'GH', PhoneFormat::NATIONAL); // 024 412 3456 LaraPhone::countryName('GH'); // Ghana LaraPhone::supportedCountries(); // ['AC', 'AD', 'AE', ...]
Formatting
A PhoneNumber can be formatted in various ways:
use DevSarfo\LaraPhone\Enums\PhoneFormat; $phone = new PhoneNumber('0244123456', 'GH'); $phone->format(PhoneFormat::NATIONAL); // 024 412 3456 $phone->formatE164(); // +233244123456 $phone->formatInternational(); // +233 24 412 3456 $phone->formatRFC3966(); // tel:+233-24-412-3456 $phone->formatNational(); // 024 412 3456
Passing
libphonenumber\PhoneNumberFormatstill works but is deprecated and will be removed in 2.0. UseDevSarfo\LaraPhone\Enums\PhoneFormatinstead.
For anything the package doesn't wrap, $phone->toPhoneNumber() returns the underlying libphonenumber\PhoneNumber.
Exceptions
Every exception the package throws implements DevSarfo\LaraPhone\Exceptions\LaraPhoneException:
use DevSarfo\LaraPhone\Exceptions\LaraPhoneException; try { $e164 = phone($input, 'GH')->formatE164(); } catch (LaraPhoneException $e) { // the number couldn't be parsed, or a country code is unsupported }
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 456for 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
- Bernard Sarfo Twumasi
- Joshua Gigg - libphonenumber for PHP (Lite)
- Google - libphonenumber
- All Contributors
License
The MIT License (MIT). Please see License File for more information.