Simple Sms Laravel Package

Getting Started

This release (3.1.1) is a maintenance bump: a Laravel 5.4 compatibility fix and one new carrier (US Cellular) in the carrier lookup table. Nothing in it changes the public API, so existing integrations keep working — but if you were pinned below 3.1.1 on a 5.4 app, bump the constraint.

1. Install and pin the version

   composer require vendor/package:^3.1.1
   

   On Laravel 5.4 you must also register the service provider manually in config/app.php (providers array) — auto-discovery only helps you from 5.5 onward. This is precisely what the "Laravel 5.4 Fix" addresses, so don't skip the bump and assume registration still works.

2. Publish config and set credentials

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   

   Put any API key/timeout values in .env, not in the published config, and add them to .env.example so teammates and CI don't silently run with empty credentials.

3. Look first at: the config file (carrier list, cache driver, endpoint), the carrier enum/constant class (that's where US Cellular landed), and the package's changelog for the 5.4 fix details.

4. First use case — normalize a number, then resolve its carrier:

   $phone = PhoneNumber::parse('+1 312 555 0142'); // always E.164
   $carrier = Carrier::for($phone);                // now may return US Cellular
   

   Verify the happy path against a known US Cellular number before touching anything else; that single assertion tells you whether the new carrier map is live in your install.

Implementation Patterns

Wrap the package, don't sprinkle it. Bind a thin CarrierResolver service in your container that takes the raw input, normalizes it, calls the package, and returns your own DTO. When the carrier list or method names shift in a future release, you edit one class instead of forty call sites.

Model casting / accessor pattern. For stored numbers, add a phone_carrier column and populate it in an observer or a dedicated job rather than in the request cycle — carrier lookups are I/O, and you don't want them on the hot path of a form submit.

Cache aggressively, key on E.164. Carrier lookups are effectively immutable per number short of porting. A Cache::remember("carrier:{$e164}", now()->addDays(30), ...) wrapper cuts cost and latency dramatically. Remember that ported numbers do change carrier, so pick a TTL you can defend (30–90 days) and invalidate on user profile updates.

Queue the enrichment. Dispatch a job on user creation/phone change; make it ShouldBeUnique keyed on the normalized number so a burst of signups doesn't fan out into duplicate lookups.

Validate before you look up. Run the number through your validator/normalizer first. Sending garbage to a lookup endpoint returns either an exception or a misleading "unknown" that pollutes your cache with a long TTL.

Testing. Freeze the carrier map in tests — assert against numbers you control, and use the package's fake/mock hook (or bind a stub CarrierResolver) so CI never hits the network. Add one test asserting US Cellular resolves, so a future regression in the carrier table surfaces immediately.

Upgrade workflow. Treat carrier-table releases as data updates, not code changes: bump, run your carrier test suite, deploy. Keep the composer constraint at ^3.1 so patch-level carrier additions flow through on your normal composer update cadence.

Gotchas and Tips

• The 5.4 fix has a version floor. If you're on Laravel 5.4 and composer update is held back by other constraints, you can stay stuck on a broken provider registration without noticing. Run composer show vendor/package and confirm you're actually on 3.1.1+.
• 5.4 means no auto-discovery. New team members adding the package on a legacy 5.4 app will hit "class not found" unless the provider and any aliases are registered in config/app.php. Document it in the README of your app, not just here.
• Carrier strings are display data. US Cellular will show up in logs, exports, and possibly your UI. Don't compare against hard-coded strings across the codebase — compare against the package's constants or your own enum, or you'll be doing a find-and-replace on the next carrier rename.
• Don't assume the list is exhaustive. New carriers appear in patch releases like this one. Design your fallback path ('unknown' / null) and make sure UI handles it before the marketing team asks why some users show a blank field.
• Ported numbers lie. A number that was US Cellular last year may not be today. If carrier data drives pricing, routing, or compliance decisions, treat it as a hint and re-verify at the moment of consequence.
• Debugging lookups: log the normalized number alongside the raw input. Nine times out of ten an "unknown carrier" is a formatting problem upstream, not a missing carrier.
• Rate limits and timeouts: set an explicit HTTP timeout (2–3s) and a failure path that degrades to null rather than throwing in a request. A carrier lookup should never be able to 500 your signup form.
• Extension point: if the package exposes a carrier-map contract, prefer extending it over editing vendor files — that's how you add a carrier the package hasn't shipped yet without forking.
• Changelog discipline: releases this small are easy to ignore, and that's exactly when a ^3.x minor slips a behavioral change past you. Skim the notes on every bump; the cost is thirty seconds.