moonlydays/laravel-mno

Utilities for configuring interactions with operator phone numbers and subscribers.

1.4.0 2026-04-14 07:55 UTC

Requires

• php: ^8.2
• giggsey/libphonenumber-for-php: ^9.0.27
• giggsey/locale: ^2.9
• illuminate/contracts: ^11.0||^12.0||^13.0
• spatie/laravel-package-tools: ^1.93

Requires (Dev)

• larastan/larastan: ^3.9.4
• laravel/pint: ^1.29
• nunomaduro/collision: ^8.9.3
• orchestra/testbench: ^10.11.0||^9.0.0
• pestphp/pest: ^3.8.6
• pestphp/pest-plugin-laravel: ^3.2
• rector/rector: ^2.4.1

MIT

• Daniil Basiuc-Brinzei

• operator
• phone
• laravel
• msisdn
• mno

README

Laravel package for validating, normalizing, and working with MSISDN phone numbers tied to a single Mobile Network Operator. A wrapper around giggsey/libphonenumber-for-php with integration into Laravel's validation system, Eloquent casts, and facades.

Released under the MIT License.

Requirements

• PHP 8.2+
• Laravel 11, 12, or 13

Installation

composer require moonlydays/laravel-mno

Publish the configuration file:

php artisan vendor:publish --tag="mno-config"

Configuration

Set up the environment variables:

MNO_NAME=MTS
MNO_COUNTRY=RU
MNO_NETWORK_CODES=910,911,912
MNO_MIN_LENGTH=10
MNO_MAX_LENGTH=10

Variable	Description
MNO_NAME	Name of the mobile network operator
MNO_COUNTRY	ISO 3166-1 alpha-2 country code (e.g., RU, TZ)
MNO_NETWORK_CODES	Comma-separated National Destination Code (NDC) prefixes for the operator
MNO_MIN_LENGTH	Minimum national number length (optional — inferred from libphonenumber metadata)
MNO_MAX_LENGTH	Maximum national number length (optional — inferred from libphonenumber metadata)

When MNO_MIN_LENGTH / MNO_MAX_LENGTH are unset, the package infers the length from libphonenumber metadata for the configured country, walking the number_types priority list in config/mno.php (defaults to Mobile, then General).

Usage

Creating a PhoneNumber

use MoonlyDays\MNO\Values\PhoneNumber;

// Parse, throwing InvalidPhoneNumberException on failure
$phone = PhoneNumber::from('[phone]');
$phone = PhoneNumber::from('9101234567', 'RU');

// Safe parse, returning null on failure
$phone = PhoneNumber::tryFrom('invalid'); // null

// Global helper
$phone = phoneNumber('[phone]');

PhoneNumber is a lightweight value object wrapping libphonenumber's native PhoneNumber. It implements Stringable (casting to string produces the E.164 form), JsonSerializable (serializes as E.164), and Castable (can be used directly as an Eloquent cast). It also uses Laravel's Macroable and Tappable traits.

Formatting

$phone = PhoneNumber::from('[phone]');

$phone->e164();          // "[phone]"
$phone->national();      // "8 [phone]"
$phone->international(); // "[phone]"
(string) $phone;         // "[phone]"

Retrieving number components

$phone = PhoneNumber::from('[phone]');

$phone->countryCode();      // 7
$phone->countryIso();       // "RU"
$phone->nationalNumber();   // "9101234567"
$phone->networkCode();      // "910"
$phone->subscriberNumber(); // "1234567"
$phone->toPhoneNumber();    // underlying libphonenumber\PhoneNumber

Two PhoneNumber instances can be compared via $a->equals($b) (equality is based on the E.164 form).

Validation

use Illuminate\Validation\Rule;

// Use the Rule::phoneNumber() macro — picks up defaults from config
$request->validate([
    'phone' => ['required', Rule::phoneNumber()],
]);

use MoonlyDays\MNO\Rules\PhoneNumberRule;

// Customize the rule fluently
$request->validate([
    'phone' => [
        'required',
        (new PhoneNumberRule())
            ->country('RU', 'BY', 'KZ')
            ->networkCodes('910', '911')
            ->minLength(10)
            ->maxLength(10),
    ],
]);

Validation failures translate the following keys, which you can publish or override in your own language files:

• validation.msisdn.invalid
• validation.msisdn.country
• validation.msisdn.min_length (receives :min)
• validation.msisdn.max_length (receives :max)
• validation.msisdn.network_code

Overriding the default rule

PhoneNumberRule::defaults() lets you swap in a custom resolver used by Rule::phoneNumber():

use MoonlyDays\MNO\Rules\PhoneNumberRule;

PhoneNumberRule::defaults(fn () => (new PhoneNumberRule())
    ->country('RU')
    ->minLength(10)
    ->maxLength(10));

Request macro

The service provider registers a phoneNumber macro on Illuminate\Http\Request:

$phone = $request->phoneNumber('phone');           // PhoneNumber or null
$phone = $request->phoneNumber('phone', $default); // with fallback

Eloquent cast

Since PhoneNumber implements Castable, you can use it directly as an Eloquent cast. PhoneNumberCast is also available if you prefer to be explicit:

use Illuminate\Database\Eloquent\Model;
use MoonlyDays\MNO\Values\PhoneNumber;

class User extends Model
{
    protected $casts = [
        'phone' => PhoneNumber::class, // or PhoneNumberCast::class
    ];
}

$user->phone = '[phone]';
$user->save(); // Stored as E.164: "[phone]"

$user->phone instanceof PhoneNumber; // true
$user->phone->national();            // "8 [phone]"

The cast accepts either a string or a PhoneNumber instance when setting, and always persists the E.164 form.

MNO facade

use MoonlyDays\MNO\Facades\MNO;

MNO::countryIsoCode(); // "RU"
MNO::country();        // Country instance for "RU"
MNO::countryCode();    // 7
MNO::carrierName();    // "MTS"
MNO::carrier();        // Carrier instance for the configured MNO
MNO::networkCodes();   // ["910", "911", "912"]
MNO::minLength();      // 10
MNO::maxLength();      // 10
MNO::exampleNumber();  // PhoneNumber|null
MNO::numberTypes();    // array<NumberType>

The facade resolves the MnoService singleton, which is also bound to the container alias mno and can be injected directly.

Country and Carrier value objects

use MoonlyDays\MNO\Values\Country;
use MoonlyDays\MNO\Values\Carrier;

// Country — wraps an ISO 3166-1 alpha-2 code
$country = Country::from('RU');       // throws InvalidCountryException on unknown code
$country = Country::tryFrom('RU');    // returns null on failure

$country->isoCode();               // "RU"
$country->countryCode();           // 7
$country->name();                  // "Russia"
$country->exampleNumber();         // PhoneNumber|null
$country->isMobileNumberPortable(); // bool
$country->carriers();              // array<string, Carrier> — all carriers with allocations

// Carrier — a carrier within a country
$carrier = Carrier::from('RU', 'MTS');    // throws InvalidCarrierException on miss
$carrier = Carrier::tryFrom('RU', 'MTS'); // returns null on failure

$carrier->name();             // "MTS"
$carrier->country();          // Country instance
$carrier->networkCodes();     // ["910", "911", "912"] — NDC prefixes
$carrier->prefixes();         // ["7910", "7911", "7912"] — with country code
$carrier->matches($phone);    // true if the phone number belongs to this carrier
$carrier->owns('910');        // true if the carrier owns this NDC

Artisan command

Inspect the configured MNO, a country, or a specific carrier:

php artisan mno:show              # show configured operator details
php artisan mno:show RU           # show country info with carrier list
php artisan mno:show RU MTS       # show carrier details with network codes

Extending via macros

PhoneNumber uses the Macroable trait, so you can add project-specific helpers:

use MoonlyDays\MNO\Values\PhoneNumber;

PhoneNumber::macro('isRussian', function (): bool {
    /** @var PhoneNumber $this */
    return $this->countryIso() === 'RU';
});

PhoneNumber::from('[phone]')->isRussian(); // true

Testing

composer test       # Pest
composer analyse    # PHPStan (level 5)
composer lint       # Laravel Pint