- How do I install and set up Laravel Phone in my Laravel project?
- Run `composer require propaganistas/laravel-phone` to install. The package auto-discovers the service provider. Add a translation key `'phone' => 'The :attribute field must be a valid number.'` to your `validation.php` language files for each supported locale. No additional configuration is needed for basic usage.
- Which Laravel versions does this package support?
- Laravel Phone supports Laravel 8.x, 9.x, and 10.x. Check the [Packagist page](https://packagist.org/packages/propaganistas/laravel-phone) for the latest version compatibility. The package follows Laravel’s semantic versioning and maintains backward compatibility within major versions.
- Can I validate phone numbers by country in Laravel forms?
- Yes. Use the `phone:US,BE` syntax in validation rules to restrict numbers to specific countries (e.g., US and Belgium). For dynamic country validation, append `_country` to your field name (e.g., `phone` and `phone_country`) or pass a custom country field name to the validator. Example: `'phone' => 'phone:US,BE'` or `(new Phone)->country(['US', 'BE'])`.
- How should I store phone numbers in my database for best results?
- Store phone numbers as **E.164 format** (e.g., `+1234567890`) for consistency with telephony APIs like Twilio. Use the `E164PhoneNumberCast` for Eloquent models to enforce this. For user-facing display, store raw input separately or use the `RawPhoneNumberCast` if you need to preserve formatting. Avoid storing unvalidated strings without country context.
- Does Laravel Phone work with international numbers, or is it US/EU-only?
- Laravel Phone supports **global phone numbers** via Google’s libphonenumber, including validation, parsing, and formatting for over 200 countries. Use `phone:INTERNATIONAL` for unrestricted validation or specify allowed countries (e.g., `phone:US,IN,BR`). The package handles edge cases like shared number spaces (e.g., North America) and special service numbers.
- How do I format phone numbers for display or dialing in Blade templates?
- Use the `formatForCountry()` method on a `PhoneNumber` object to render numbers in local format (e.g., `+1 (234) 567-8900` for US). In Blade, Eloquent casts auto-convert to formatted strings: `{{ $user->phone }}`. For national dialing format, use `formatNational()`. For E.164 (API-friendly), use `formatE164()`. Example: `$phone->formatForCountry('US')`.
- Can I compare two phone numbers for equality, even if formatted differently?
- Yes. Use the `equals()` method on a `PhoneNumber` object to compare numbers regardless of formatting. Example: `$phone1->equals($phone2)`. This method normalizes numbers to E.164 internally, so `+1234567890`, `1-234-567-8900`, and `(234) 567-8900` are treated as equal. Ideal for deduplication or user profile matching.
- What are the performance implications of parsing/formatting large volumes of phone numbers?
- Parsing/formatting phone numbers involves regex and geopolitical data, which can introduce **moderate CPU overhead**. For high-throughput APIs (e.g., processing 10K+ numbers), benchmark in staging and consider caching parsed `PhoneNumber` objects. Avoid parsing the same number repeatedly in loops. The package is optimized for typical web traffic but may require scaling for bulk operations.
- How do I handle legacy phone number data stored as raw strings in my database?
- Use Eloquent observers or model boot methods to normalize legacy data during migration. Example: Cast the field to `RawPhoneNumberCast` and update records with `PhoneNumber::parse($rawNumber, $countryCode)->formatE164()`. Test thoroughly with a sample dataset to catch edge cases (e.g., invalid formats, missing country codes). Document the migration process for future developers.
- Are there alternatives to Laravel Phone for phone number handling in Laravel?
- Alternatives include **symfony/validator** (with custom constraints) or **libphonenumber-for-php-lite** (standalone). However, Laravel Phone is the most **Laravel-native** solution, offering seamless integration with Eloquent, validation, and Blade. It abstracts complexity (e.g., country-specific rules) while providing utility methods like geolocation and number type detection, which standalone libraries lack.