Laravel-Phone: countries, types and leniency share one parameter slot
Phone number functionality for Laravel
At a glance
- What is it?
- Laravel-Phone wraps a lite port of Google's libphonenumber in a validation rule, two Eloquent casts and a utility class, and its readme documents the syntax precisely enough that the overloaded parameter slot becomes the whole design. It also requires a translation line to be added by hand to every language file, and it uses a lite metadata build rather than Google's full library.
- Who is it for?
- Laravel-Phone is a reasonable choice if your application stores or accepts phone numbers and you want libphonenumber's parsing rather than a regular expression, because the cast classes remove the parse-and-format step from your model code and the validation rule covers countries, number types and a leniency switch in one expression.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 44 days ago.
- What is it written in?
- Mainly PHP, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- Propaganistas/Laravel-Phone3,042 ★ · +5
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| Propaganistas/Laravel-Phone | 3k | 3k |
5 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The validation message is not shipped and goes into every language file
Installation is one command:
composer require propaganistas/laravel-phoneand one sentence: the service provider gets discovered automatically by Laravel. The second step is the one that catches people. In your languages directory you must add an extra translation in every validation.php language file, with the key phone and the message text. The package does not ship the message, and the tree confirms why: there is a src directory and a tests directory and a license file and an upgrading note, and no lang directory anywhere. So for an application with thirty locales, the rule works immediately but the message is missing until somebody edits thirty files by hand. That is a small thing and an entirely avoidable one for anyone who notices it, but it is the difference between installing the package and being able to show a validation error.
One parameter slot takes countries, types, negations and a switch
Everything the validation rule can express goes after a colon in one comma-separated list, and the same slot means different things depending on what is in it. A bare list of two-letter codes restricts the allowed originating countries, and the page notes those codes should follow the ISO 3166-1 alpha-2 standard. A number type such as mobile or fixed_line constrains the line type, and the page says any type defined by the library is allowed, not just those two. A type prefixed with an exclamation mark is blacklisted instead, with the explicit restriction that you can never use whitelisted and blacklisted types at the same time. The literal INTERNATIONAL is neither a country nor a type: it opens the rule to any properly formatted foreign number alongside the listed ones, so the example is a union of international and Belgium rather than an intersection.
LENIENT checks the length of a number and nothing else
The one weakening switch in the rule is described in a single sentence that is easy to skim past. You can enable lenient validation with the LENIENT parameter, and with leniency enabled only the length of a number is checked instead of actual carrier patterns. So the two modes differ in exactly what they validate: the default checks the number against the patterns the metadata knows for each country, and the lenient one checks that the string is a plausible length. Everything the rule is for beyond rejecting typos and impossible values is switched off, and it is switched off by naming it in the same position where a country code would otherwise go. The documented pair of forms is the keyword and the method:
'my_input' => 'phone:LENIENT',
// 'my_input' => (new Phone)->lenient()Nothing on the page suggests when to choose it, and nothing warns that it is weaker.
The two casts store two different formats from the same field
Two cast classes are provided for Eloquent attributes, and they differ in what ends up in the database. Both cast the stored value to a PhoneNumber object on read, so reading either gives you the same object. On write they diverge: the raw cast mutates the database value to the raw input number, while the E164 cast writes a formatted E.164 number. That is the whole difference, and it is a storage decision rather than a display one. The raw format preserves what the user typed, which may be local formatting, spaces, punctuation or none, and which cannot be parsed without knowing the country. The page says so directly: in case of the raw cast, the cast needs to be hinted about the phone country in order to properly parse the raw number into a phone object, and the same hint is needed for the E164 cast whenever the incoming value is not already in international format.
The country attribute has to be set first or the cast throws
There is an ordering constraint on model assignment and the readme gives it a heading of its own with a warning marker. Because of the nature of the E164 cast, a valid country attribute is expected if the number is not passed in international format, and since Laravel applies casts instantly when setting an attribute, the country attribute must be set before the phone number attribute. Otherwise the cast encounters an empty country value and throws what the page calls an unexpected exception. So a fill call that lists the phone key before the country key fails, and the failure surfaces from the cast rather than from validation. The README shows both incorrect and corrected examples, setting the country attribute first in the corrected versions.
The global default is a static property rather than a setter
Country restrictions can be set once for the whole application, and the mechanism is worth reading precisely. In a service provider you write an assignment to the rule class, setting a static member named for the default country to an array of codes. That is a public static property being assigned, not a setter method being called, which means the default is process-wide mutable state on a shared rule class rather than configuration held per rule or per form request. Individual rules can still override it, and the two examples make the precedence explicit: a rule with no parameters validates against the defaults, while a rule naming a country validates only against that country and ignores the defaults. The three examples on the page also order the same pair of countries differently, as US then BE, then BE then US, which is harmless for a set and a small reminder that the order carries no meaning.
The demo is a herokuapp address and three badges are identical
The page opens by pointing at a live demo for the behaviour of the package, and the address it points at is on the herokuapp.com domain. That is a hosted platform whose free tier has been withdrawn and whose domain is not under the project's control, so the demo's longevity is not something the repository can promise, and no alternative host is named. The badge row above it has the same shape. The workflow badge points at a tests workflow, and then the Packagist badge appears three times, identically, one after another. Neither of these is a defect in the package. They are the two things a reader sees first, and both of them understate how the project is actually distributed: the tests badge and a single package badge say nothing about the upgrade notes that sit in the tree, which is where the breaking changes between the current major version and the previous one are recorded.
Editorial conclusion
Laravel-Phone is a reasonable choice if your application stores or accepts phone numbers and you want libphonenumber's parsing rather than a regular expression, because the cast classes remove the parse-and-format step from your model code and the validation rule covers countries, number types and a leniency switch in one expression. It is a poor fit if you want the validation message localised for free, since that is a manual step per language, and a poor fit if you store raw input, because the raw cast only parses correctly when it is told the country. Before you wire it in, add the translation line, decide which of the two storage formats you actually want, and if you keep the E164 cast remember the assignment order, because the failure when it is wrong is described as unexpected.
Frequently asked questions
What does the Propaganistas Laravel Phone package do?
It adds phone number functionality to Laravel based on the PHP port of Google's libphonenumber, which the readme points at as a lite build of that library. It provides a validation rule usable as a keyword or as a class, two Eloquent cast classes, and a utility class for formatting, number information and equality comparison.
How do I install Laravel-Phone?
Run composer require propaganistas/laravel-phone; the service provider is discovered automatically. You then have to add a phone translation entry to every validation.php language file in your languages directory by hand, because the package ships no lang directory.
What does the LENIENT parameter do in the Laravel Phone validation rule?
It enables lenient validation, where only the length of a number is checked instead of actual carrier patterns. It is written as the keyword LENIENT after the rule, or as the lenient method on the rule class.
What is the difference between RawPhoneNumberCast and E164PhoneNumberCast?
Both cast a stored value to a PhoneNumber object on read. On write the raw cast stores the raw input number, while the E164 cast stores a formatted E.164 number. Both need to be told the country when the value is not already in international format.
How does the Laravel Phone validation rule express countries and number types?
Everything goes after the rule name as a comma-separated list. Two-letter ISO 3166-1 alpha-2 codes restrict the allowed countries, types such as mobile or fixed_line can be whitelisted or blacklisted with a leading exclamation mark but never both, and the literal INTERNATIONAL additionally accepts any properly formatted foreign number. A global default country list can be set on the rule class and overridden per rule.
Where can I see Laravel-Phone running?
The readme points at a live demo hosted on a herokuapp.com address and asks you to check the behaviour of the package there. No other demo host is named, and the tests in the repository run through a PHPUnit configuration file named with the .dist suffix.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/propaganistas-laravel-phone)Star history chart for your README
[](https://hysenlabs.com/projects/propaganistas-laravel-phone)Was this useful?