Somali Phone Laravel Package

Technical Evaluation

Architecture fit

• Narrow, single-purpose domain package: phone parsing/normalization plus prefix-based lookup tables. No database, no external API calls at runtime, no queue or cache dependency — it is pure computation over a bundled data set.
• Ships idiomatic Laravel integration points (validation rule, string rule, CastsAttributes cast), so it slots into the framework's existing extension surfaces rather than requiring custom plumbing.
• Strong fit for a shared internal package or a bounded-context value object in an app that already touches Somali users (onboarding, KYC, SMS routing, payments).
• Weak fit for multi-country phone handling: this is Somalia-only, so it will sit alongside (not replace) a general library such as propaganistas/laravel-phone or libphonenumber. Expect two sources of truth for "is this a valid number" unless one is designated authoritative.

Integration feasibility

• Low effort: one composer require, a cast on the relevant model, and a rule on the relevant form requests. Realistically a spike in hours and a production rollout in days, dominated by data verification rather than code.
• No stated migrations or config publishing step, which keeps the blast radius small.
• Constraint: PHP 8.2+ and Laravel 12/13 only. Apps on Laravel 10/11 cannot use the Laravel integration layer as-is; if the core is framework-agnostic it may still be consumable, but that is not stated.

Technical risk

• Data staleness (highest risk). Operator, virtual network and wallet mappings are a static snapshot of the NCA numbering plan dated December 2024. Numbering plans change; there is no described update mechanism, versioning policy for the data, or deprecation path for removed prefixes.
• Number portability. Prefix-based operator lookup answers "which block was this number allocated from," not "which network is this subscriber on today." If Somalia introduces or expands mobile number portability, operator/virtual-network/wallet attribution silently degrades. This is a correctness risk for any routing, pricing or wallet decision built on top.
• False negatives block users. An unrecognized prefix likely fails validation, which surfaces as signup or checkout drop-off for real customers on newly allocated ranges. Failure mode is silent and customer-facing.
• Vendor concentration. A v1.0.0 from a single publisher with no track record. Abandonment risk is real for a package whose value is a maintained data set.
• Commercial coupling. The WAAFI support check encodes a business relationship into a data table; the package owner's commercial interests and our roadmap may diverge.
• Scope creep of "wallet lookup." Determining which mobile money wallet a number maps to is a business rule, not a phone-parsing concern; hardcoding it in a third-party package removes our ability to change pricing, routing or eligibility without a fork.

Key questions

1. What is the update cadence and process for the numbering-plan data, and how will we be notified of changes?
2. Does the package expose the raw lookup data so we can override or extend mappings without forking?
3. Is "operator" documented as allocation-block identity rather than current carrier? What is the stated behavior under portability?
4. Is the core (parser/normalizer/lookup) usable outside Laravel, or is the whole package framework-coupled?
5. What are the license, test coverage, CI status and maintainer/backing details? Are the prefix tables backed by tests against real-world samples?
6. What are the defined behaviors for unknown, ambiguous and invalid inputs — exception, null, or validation failure?
7. Are Somali and English error messages published to lang/ for override, or hardcoded?
8. Is the WAAFI check purely prefix-derived, or does it imply an API/partnership dependency?

Integration Approach

Stack fit

• Laravel 12 + PHP 8.2 is the supported floor; the package declares Laravel 13 support ahead of its release, which is a forward-compatibility signal but also an untested-by-us claim until Laravel 13 ships.
• Natural insertion points: form requests (validation rule), model casts (normalization at write time), and a canonical E.164 column for storage and indexing.

Migration path

• Greenfield adoption is trivial. Brownfield adoption should be staged: add the dependency read-only, then normalize, then enforce.
• Backfill existing numbers with a one-off command or queued job using the normalizer, writing to a new normalized column before any validation rule is enabled on write paths. Do not retrofit validation onto existing records without a dry-run report of what would now be rejected.

Compatibility

• Audit the dependency tree for packages pinned below Laravel 12 or PHP 8.2 before committing; mixed framework versions in a monorepo complicate a shared internal adoption.
• Coexistence with an existing general-purpose phone library needs an explicit decision on which is authoritative for validation vs. formatting vs. operator attribution.

Sequencing

1. Spike in a branch; run the parser against a representative sample of real production numbers, including Arabic-Indic digit inputs and edge formats.
2. Ship normalization + read-only operator/virtual-network lookup behind a flag; log results, change nothing user-facing.
3. Backfill the normalized column; reconcile mismatches before enforcing anything.
4. Enable the validation rule on high-value write paths (registration, checkout) with a monitored rejection rate.
5. Evaluate the wallet/WAAFI check last, as a separate business decision rather than part of the technical rollout.

Operational Impact

Maintenance

• The code is near-zero maintenance; the data is not. Budget a recurring review against NCA publications (at minimum annually, ideally quarterly) and track package releases for updated tables.
• Plan for the fork/vendor contingency: because the value is a data table, extracting and self-hosting the mappings is cheap insurance if the package stalls.

Support

• Minimal runtime support surface — no infrastructure, no secrets, no third-party uptime dependency. Support load concentrates on one question: "why was this real number rejected?"
• Somali-language error messages reduce end-user support contacts; confirm they are overridable so tone and dialect stay under product control.

Scaling

• Effectively free. Pure CPU work on a short string, no I/O, cache-friendly. Negligible at any plausible volume; no capacity planning required.

Failure modes

• Unknown/newly allocated prefix → validation failure → user cannot register or pay. Detect via rejection-rate monitoring and a fallback path that accepts and flags rather than hard-blocks.
• Misattributed operator or wallet → wrong SMS route, wrong pricing, wrong disbursement channel. Detect via reconciliation against actual delivery and payment outcomes.
• Portability or plan revision → silent drift with no error signal. Detect only by periodic re-validation against the live network reality.
• Package abandonment → pinned version with no patch path.
• Silent normalization divergence → two representations of the same number across systems; enforce a single canonical column.

Ramp-up

• Under a day for a Laravel developer to integrate confidently; the code is not the learning curve.
• The real ramp-up is domain literacy: Somali operator landscape, the MVNO relationships (Somnet, Soltelco, Durdur), and how wallet attribution maps to business rules. Brief product, support and finance on what an "unknown operator" result means before it reaches customers.