Somali Phone Laravel Package

Product Decisions This Supports

• Market-entry build vs. buy for Somalia/Somaliland. This is a narrow, low-cost dependency that removes the need to hand-roll a Somali numbering-plan table, normalization logic, and bilingual error strings. If Somalia is on the roadmap, this converts a multi-day research task into a composer require.
• Mobile-money and wallet coverage strategy. Wallet lookup plus a WAAFI support check lets you make product decisions about which payout/collection rails to advertise at checkout, and lets you gate "pay with mobile money" UI on a number's detected wallet rather than showing it to everyone.
• Onboarding and KYC friction. Normalization (including Arabic-Indic digits) means a single canonical E.164-style value can be stored, deduplicated, and matched across signup, login, and remittance flows — reducing failed-OTP and "number already registered" support tickets.
• Messaging and notification cost/routing. Operator and virtual-network resolution supports per-operator SMS routing decisions, sender-ID constraints, and delivery-cost modeling by network — useful input to an SMS vendor negotiation or routing config.
• Localization commitment. English and Somali error messages are a small but real signal you can ship a Somali-first UX without building a translation layer for validation strings.
• Not supported: fraud or identity assurance. This is a static prefix lookup, not a live HLR/network query. It cannot confirm a number is currently active, reachable, or owned by the person claiming it. Do not let it stand in for OTP verification or a real number-intelligence vendor.

When to Consider This Package

Adopt when:

• Somalia/Somaliland is a live or near-term market, and phone number is a primary identifier (fintech, remittance, wallet, marketplace, SMS-heavy product).
• You need canonical normalization at the boundary (form requests, API ingestion, imports) and want that enforced consistently via a validation rule and an Eloquent cast rather than scattered helpers.
• You need operator/MVNO/wallet attribution for routing, pricing, or product gating — and prefix-level accuracy is sufficient for the decision.
• Your stack is PHP 8.2+ on Laravel 12 or 13.

Look elsewhere or defer when:

• Laravel version gate. Support is limited to Laravel 12/13. On Laravel 10/11 this requires an upgrade first — treat the framework upgrade, not the package, as the real cost.
• Multi-country needs. This is single-country by design. If you need 10+ markets, a generalist library (e.g. giggsey/libphonenumber-for-php) covers Somalia adequately and avoids maintaining one dependency per country.
• You need verified number intelligence. If the requirement is "is this number live and does it belong to this person," you need an HLR/lookup API, not a static table.
• Number portability matters. Prefix-derived operator/wallet attribution is an inference. If Somalia's MNP regime or wallet-switching behavior makes prefixes unreliable for your use case, validate with real traffic before gating payments on it.
• You can't tolerate data staleness. The operator data is a December 2024 NCA snapshot. Prefix plans and MVNO rosters drift; you need a plan for picking up updates.
• Trivial volume. For a few hundred records in one internal tool, a lookup table in your own config may be simpler than a third-party dependency.

Gating questions before adoption: single-maintainer/vendor concentration risk, release cadence, whether numbering-plan refreshes ship as patch releases, license terms, and whether an issue/PR path exists for correcting an operator mapping when you find one wrong.

How to Pitch It (Stakeholders)

To executives: For roughly the cost of a single engineering day, this package lets us accept Somali phone numbers in any format customers actually type — including Arabic-Indic digits — and automatically identify the carrier, the virtual network, and the mobile-money wallet behind each number. That directly supports Somali market entry, reduces signup drop-off, and gives us the data to route SMS more cheaply and decide which wallet rails to surface at checkout. It is a small, replaceable dependency, not a platform commitment.

To engineering: A focused Laravel package providing a validation rule, a string rule, and an Eloquent cast for Somali mobile numbers, with normalization and NCA-based operator/MVNO/wallet resolution, bilingual error messages, PHP 8.2+, Laravel 12–13. Integration surface is deliberately small — one rule, one cast, one value object — so it can be swapped or forked cheaply.

To risk/compliance: Be explicit on two points. First, this performs format validation and prefix inference, not verification — it is not a substitute for OTP or a number-intelligence provider, and it must not be represented as identity assurance. Second, operator and wallet attribution is derived from a static December 2024 NCA snapshot; it is best-effort and should not be the sole control on any payment or eligibility decision. Recommend we log detected-vs-actual mismatches for the first quarter to measure real accuracy before relying on it for wallet gating. Also note the package is at v1.0.0 with a single release — low blast radius, but we should pin the version and track upstream activity.