Tomato Locations Laravel Package

Product Decisions This Supports

• One canonical address model instead of per-squad dropdown lists. A country → state → city → area hierarchy as real Eloquent models gives signup, checkout, profile, store locator, and B2B onboarding a single source to read from. The PM decision this forces is "we standardize on one location schema" versus "each team keeps its own list" — and that call is much cheaper to make now than after three features ship with divergent tables.
• Unblocks a cluster of roadmap items at once. Multi-country signup, delivery/shipping zones, tax jurisdictions, regional pricing, marketplace seller onboarding by region, and warehouse/store locators all join against a geographic key. Having that key on day one turns several "big" initiatives into feature work rather than foundational schema work.
• Market expansion becomes sequencing, not engineering. Adding a new country is "seed and verify the region, attach its config" rather than "design location tables again." That directly changes how many markets fit in a quarter and how confidently you can put them on a roadmap.
• Build vs. buy on master data clears the bar it usually fails. The alternative is sourcing a global city dataset, importing it, dedup-ing it, and building admin CRUD to maintain it — a thankless, ongoing workstream with a refresh burden nobody wants to own. Borrowing here is the sane answer, but the PM still owns the follow-on decision: who is responsible for keeping the data fresh.
• A genuinely hard-to-reverse call. The location schema gets copied onto users, orders, warehouses, tax tables, and shipping rules. Changing it after launch means migrating live address data across every dependent table. Decide before the first market launch, not after. This is the single most important PM framing for the package.
• Size the "we own it" line item honestly. Zero stars, zero dependents, single maintainer, last release May 2024. This is not a popularity-backed bet — it's a small MIT code asset we can read, extend, and if necessary vendor outright. Treat adoption as "we are effectively the largest consumer and should plan to be the maintainer of last resort," and budget accordingly. The blast radius of abandonment is a few hours of migration/model work, which is what keeps this a low-risk decision despite the thin signal.

When to Consider This Package

Adopt when:

• You're on Laravel, and especially on the TomatoPHP / Filament admin stack — integration cost is near zero and the admin CRUD is effectively free.
• You need CRUD plus seeded reference data with an admin UI, not just a read-only dataset dump someone has to import by hand.
• Your address needs are hierarchical but not validation-grade — structured country/state/city selects, not authoritative postal-address verification.
• You want migrations and Eloquent models you can extend and relate to your own tables, rather than wrapping and paying for an external geo API.
• Your team can accept community-package maintenance risk and will name someone responsible for data freshness (renamed cities, changed ISO codes, disputed borders).

Look elsewhere when:

• You need authoritative address validation, geocoding, or postal-code accuracy — use a commercial provider (Google, Loqate, Smarty, Mapbox) and treat this only as UI scaffolding.
• Your product is high-volume geospatial — polygon containment, radius search, drive-time routing — you want PostGIS-style geo storage, not a plain relational hierarchy.
• You're not on Laravel/Tomato — the value (admin UI, conventions, seeded models) largely disappears, and you'd be taking a dependency for tables you could own outright.
• You need a vendor SLA, security review, or guaranteed refresh cadence — none of that exists here.
• Data licensing, provenance, or residency matters to legal — the bundled seed set's origin isn't documented in the release; verify before it's customer-facing.
• Community health is a gating criterion in your org — 0 stars / 0 dependents / release notes that are just a diff link is a real signal, even if the code is fine.

How to Pitch It (Stakeholders)

To executives (one paragraph): This package gives us the country/region/city backbone that address forms, shipping zones, and regional pricing all sit on, built on the Laravel stack we already run. It takes the "design location tables, source the data, build the admin screens" workstream off the next milestone so the team can spend that time on the customer-facing feature instead. The trade-off is honest and small: an open-source dependency with a single-maintainer profile and no real release notes, which we version-pin, review on each bump, and explicitly assign an owner for keeping the location data current. Low cost — but it belongs on the maintenance ledger, not assumed free.

To engineering: Conventional Laravel package — publishable migrations, Eloquent models, seeders, optional Filament admin resources. Extend the models; don't fork. Treat the bundled dataset as a seed, not a source of truth: define an import/refresh path up front and don't let it quietly become canonical. Put location lookups behind a thin service/repository so swapping in a commercial validation or geocoding provider later is a one-file change rather than a schema migration. Pin ^1.2 in composer.json, run migrations against a restored production snapshot to catch table and index collisions, and seed as a batched background job — a full city set is minutes of writes, not a deploy hook. Cache the read path with a long TTL and invalidate on re-seed, and index the country_id/city_id foreign keys we add on our own tables.

On v1.2.5 specifically: a patch bump whose release body is only a compare link — no changelog, no migration note, no CVE reference. Expected for a patch, but it means nothing here changes the buy/borrow calculus, and it isn't evidence of active roadmap investment upstream. Action: diff the tag before upgrading, confirm no model or migration changes, then pin.

Overall recommendation: adopt behind an abstraction, with data-freshness ownership explicitly assigned and an internalized-copy fallback (fork or vendor the migrations/models) pre-agreed in case upstream stalls. The blast radius of abandonment is small enough to make this a safe bet despite the thin community signal — but only if we go in planning to be the maintainer of last resort rather than assuming someone else is.