Telephone Validation
Provides validation for telephone fields using Google's libphonenumber library, supporting automatic country detection and format validation.
telephone_validation
Install
composer require 'drupal/telephone_validation:8.x-2.5'
composer require 'drupal/telephone_validation:8.x-2.4'
Overview
Telephone Validation is a Drupal module that brings powerful phone number validation to the core Telephone field type. It leverages the giggsey/libphonenumber-for-php library, which is a PHP port of Google's libphonenumber library used in Android devices worldwide.
The module can automatically detect which country a phone number belongs to and validate whether it's a valid phone number for that country. It supports two validation formats: E164 (international format with country code, e.g., +12507638884) and National (local format without country code, e.g., 2507638884).
Validation can be configured globally for all telephone fields, or customized per field instance. Site administrators can restrict valid phone numbers to specific countries, making it ideal for region-specific applications.
Features
- Validates telephone field values using Google's libphonenumber library
- Supports E164 international format validation (recommended) with automatic country detection
- Supports National format validation for single-country restrictions
- Configurable globally with default validation settings for all telephone fields
- Per-field validation settings allowing different rules for different telephone fields
- Country-based validation allowing restriction to specific countries
- Seamless integration with Drupal's constraint validation system
- Form element validation for custom forms using the 'tel' element type
- Ajax-powered settings forms for dynamic country selection based on format
Use Cases
International Contact Form
Create a contact form that accepts phone numbers from any country using E164 format. Users must enter their phone number with country code (e.g., +1 555 123 4567), and the system automatically validates that it's a real phone number from the detected country.
Country-Specific Registration
For a website serving only Canadian customers, configure telephone validation with National format and Canada as the only valid country. Users can enter their phone number without the country code (e.g., 250 763 8884), and invalid numbers will be rejected.
Multi-Region Business Application
For a business operating in multiple countries (e.g., US, Canada, and UK), use E164 format with these three countries selected. The system will only accept valid phone numbers from these specific countries while rejecting numbers from other regions.
Custom Form Validation
Add telephone validation to a custom form by using the 'tel' element type with the validateTel callback: '#element_validate' => [['Drupal\telephone_validation\Render\Element\TelephoneValidation', 'validateTel']] and optionally customize '#element_validate_settings' for format and country restrictions.
Tips
- Use E164 format for international applications as it automatically detects the country from the phone number
- National format is ideal when your application only serves users from a single country
- Empty country selection means all countries are valid - useful for truly global applications
- Per-field settings override global defaults, allowing different validation rules for different use cases
- The validation service can be used programmatically: \Drupal::service('telephone_validation.validator')->isValid($number, $format, $countries)
Technical Details
Admin Pages 1
/admin/config/content/telephone_validation
Configure the default validation settings that will be applied to all telephone form elements. These settings serve as defaults and can be overridden on a per-field basis.
Hooks 3
hook_element_info_alter
Adds default validation settings (#element_validate_settings) to the 'tel' form element type, including format and country settings from global configuration.
hook_field_info_alter
Adds the 'Telephone' validation constraint to the telephone field type, enabling automatic validation of telephone field values.
hook_form_FORM_ID_alter (field_config_edit_form)
Alters the telephone field configuration form to add validation settings (enabled checkbox, format select, country select) as third-party settings.
Troubleshooting 4
The module requires the giggsey/libphonenumber-for-php library. Install the module using Composer: 'composer require drupal/telephone_validation'. Do not download the module manually from drupal.org without using Composer.
Ensure validation is enabled for the specific field. Go to the field configuration (Manage fields > Edit field) and check the 'Enabled' checkbox under 'Telephone validation' settings.
Check the format setting. If using National format, ensure the correct country is selected. If using E164, ensure the phone number includes the country code (e.g., +1 for US/Canada).
This is expected behavior. When using National format, only one country can be selected because national numbers don't include country codes. Switch to E164 format to allow multiple countries.
Security Notes 3
- The module has official Drupal security coverage, meaning security issues are handled by the Drupal Security Team
- Phone number validation prevents storage of malformed data but does not verify phone number ownership
- Consider additional verification (SMS confirmation) for security-critical applications