hokeypok/laravel-phone

Phone number functionality for Laravel

Laravel Phone

Adds phone number functionality to Laravel and Lumen based on the PHP port of Google's libphonenumber API by giggsey.

Table of Contents

• Demo
• Installation
  • Laravel
  • Lumen
• Validation
• Utility class
  • Formatting
  • Number information
  • Helper function

Demo

Check out the behavior of this package in the demo.

Installation

Run the following command to install the latest applicable version of the package:

composer require propaganistas/laravel-phone

Laravel

If you don't use auto-discovery, open up your app config and add the Service Provider to the $providers array:

'providers' => [
   ...
   Propaganistas\LaravelPhone\PhoneServiceProvider::class,
],

In your languages directory, add an extra line for each language file:

'phone' => 'The :attribute field contains an invalid number.',

Lumen

In bootstrap/app.php, register the Service Provider

$app->register(Propaganistas\LaravelPhone\PhoneServiceProvider::class);

Validation

To validate a phone number, use the phone keyword in your validation rules array or use the Phone rule class to define the rule in an expressive way. The phone validator is able to operate in three ways.

• You either specify ISO 3166-1 alpha-2 compliant country codes yourself as parameters for the validator, e.g.:

  'phonefield'       => 'phone:US,BE',
  // 'phonefield'    => Rule::phone()->country(['US', 'BE'])

  The validator will check if the number is valid in at least one of provided countries, so feel free to add as many country codes as you like.

• You provide a dedicated country input field (keyed by ISO 3166-1 compliant country codes) to allow end users to supply a country on their own. Make sure the country field has the same name as the phone field but with _country appended for automatic discovery, or provide your custom country field name as a parameter to the validator:

  'phonefield'            => 'phone',
  // 'phonefield'         => Rule::phone()
  'phonefield_country'    => 'required_with:phonefield',

  'phonefield'            => 'phone:custom_country_field',
  // 'phonefield'         => Rule::phone()->countryField('custom_country_field')
  'custom_country_field'  => 'required_with:phonefield',

• You instruct the validator to detect which country the number belongs to using the AUTO keyword (and optionally any fallback countries):

  'phonefield'       => 'phone:AUTO,US',
  // 'phonefield'    => Rule::phone()->detect()->country('US')

  The validator will try to extract the country from the number itself and then check if the number is valid for that country. If the country could not be guessed it will be validated using the fallback countries if provided. Note that country guessing will only work when phone numbers are entered in international format (prefixed with a + sign, e.g. +32 ....). Leading double zeros will NOT be parsed correctly as this isn't an established consistency.

To specify constraints on the number type, just append the allowed types to the end of the parameters, e.g.:

'phonefield'       => 'phone:US,BE,mobile',
// 'phonefield'    => Rule::phone()->country(['US', 'BE'])->type('mobile')
// 'phonefield'    => Rule::phone()->country('US', 'BE')->mobile()

The most common types are mobile and fixed_line, but feel free to use any of the types defined here.

You can also enable more lenient validation (for example, fixed lines without area codes) by using the LENIENT parameter. This feature inherently doesn't play well with country autodetection and number type validation, so use such combo at own risk.

'phonefield'       => 'phone:LENIENT,US',
// 'phonefield'    => Rule::phone()->lenient()->country('US')

Utility PhoneNumber class

A phone number can be wrapped in the Propaganistas\LaravelPhone\PhoneNumber class to enhance it with useful utility methods. It's safe to directly reference these objects in views or when saving to the database as they will degrade gracefully to the E164 format.

use Propaganistas\LaravelPhone\PhoneNumber;

(string) PhoneNumber::make('+3212/34.56.78');              // [phone]
(string) PhoneNumber::make('012 34 56 78', 'BE');          // [phone]
(string) PhoneNumber::make('012345678')->ofCountry('BE');  // [phone]

Formatting

A PhoneNumber can be formatted in various ways:

PhoneNumber::make('012 34 56 78', 'BE')->format($format);       // See libphonenumber\PhoneNumberFormat
PhoneNumber::make('012 34 56 78', 'BE')->formatE164();          // [phone]
PhoneNumber::make('012 34 56 78', 'BE')->formatInternational(); // [phone]
PhoneNumber::make('012 34 56 78', 'BE')->formatRFC3966();       // [phone]
PhoneNumber::make('012/34.56.78', 'BE')->formatNational();      // 012 34 56 78

// Formats so the number can be called straight from the provided country.
PhoneNumber::make('012 34 56 78', 'BE')->formatForCountry('BE'); // 012 34 56 78
PhoneNumber::make('012 34 56 78', 'BE')->formatForCountry('NL'); // 00 32 12 34 56 78
PhoneNumber::make('012 34 56 78', 'BE')->formatForCountry('US'); // 011 32 12 34 56 78

// Formats so the number can be clicked on and called straight from the provided country using a cellphone.
PhoneNumber::make('012 34 56 78', 'BE')->formatForMobileDialingInCountry('BE'); // 012345678
PhoneNumber::make('012 34 56 78', 'BE')->formatForMobileDialingInCountry('NL'); // [phone]
PhoneNumber::make('012 34 56 78', 'BE')->formatForMobileDialingInCountry('US'); // [phone]

Number information

Get some information about the phone number:

PhoneNumber::make('012 34 56 78', 'BE')->getType();              // 'fixed_line'
PhoneNumber::make('012 34 56 78', 'BE')->isOfType('fixed_line'); // true
PhoneNumber::make('012 34 56 78', 'BE')->getCountry();           // 'BE'
PhoneNumber::make('012 34 56 78', 'BE')->isOfCountry('BE');      // true
PhoneNumber::make('[phone]')->isOfCountry('BE');         // true

Helper function

The package exposes the phone() helper function that returns a Propaganistas\LaravelPhone\PhoneNumber instance or the formatted string if $format was provided:

phone($number, $country = [], $format = null)