Tomato Locations Laravel Package

Technical Evaluation

Architecture fit tomatophp/tomato-locations is a reference-data package: migrations, Eloquent models, seeders, and Filament admin resources for a country → state → city → area hierarchy. It adds no runtime service, no queue worker, no external API call, and no background daemon. For a Laravel app already running the TomatoPHP/Filament admin stack, that means a leaf dependency with a small, inspectable surface area — cheap to add, cheap to remove, which is exactly the profile a TPM wants for a foundational-but-non-differentiating capability.

The critical framing for a TPM is that this is a schema and seed-data decision wearing a package's clothes. The package is swappable; the countries/cities/areas table shapes and their IDs become the join keys for shipping zones, tax jurisdictions, regional pricing, and warehouse/store locators. Once customer addresses reference those rows, the schema is effectively frozen for the life of the product. Treat the adoption decision as a one-way door and get it right before first market launch, not after.

Integration feasibility Mechanically this is a half-day to two-day integration: Composer install, service-provider discovery, publish migrations/config, migrate, seed, wire the admin resource, extend models. The real cost sits in two places a TPM must schedule explicitly:

1. Seeding. A full city/area dataset is a multi-minute, high-write-volume operation and belongs in a batched background job — never a deploy hook or a migration up().
2. Verification. v1.2.5's entire release note is a GitHub compare link. No changelog, no migration note, no CVE reference. Someone must diff the tag to know whether it is a typo fix or a silent schema change. Patch-level is declared safe; it is not verified safe.

Technical risk

• Unproven dependency (primary): 0 stars, 0 dependents, last release May 2024, single-maintainer ecosystem. Adopting makes us functionally the largest consumer. Not disqualifying for MIT code of this size, but it means no community bug-finding and no external safety net. Put it on the risk register as "vendor-and-own," not "adopt."
• Change opacity: diff-link-only patch notes mean every upgrade is an audit task. That is a recurring calendar cost, not a one-off.
• Ecosystem coupling: Filament/TomatoPHP version constraints are the usual breakage point. If our Filament major drifts, this package can pin our upgrade path — a hidden tax on framework currency.
• Data provenance and freshness: origin, license, and refresh cadence of the bundled geo dataset are undocumented. For customer-facing address data that is a legal and quality question, not a nitpick.
• Schema ownership: package-owned migrations on core reference tables collide with locally added columns and complicate rollback. Publish and code-review them as first-party schema.

Key questions

1. What changed between v1.2.4 and v1.2.5 — any model, migration, or config-key changes?
2. Which Laravel/PHP versions and DB drivers are supported at v1.2.5, and does that matrix overlap our runtime and our next upgrade target?
3. Where does the seed data come from, under what license, and who refreshes it when a city is renamed or an ISO code changes?
4. Is Filament/Tomato admin a hard or optional dependency — can we use the data layer alone if we leave that stack?
5. Do the migrations publish cleanly into an environment that already has location tables?
6. What is the rollback story, and what breaks downstream if reference rows are dropped?

Integration Approach

Stack fit Target a currently supported Laravel on MySQL 8 or PostgreSQL, with Filament only if we are already committed to it. Validate composer.json constraints against our framework version and our next upgrade target before committing. The models are plain Eloquent, so the only real coupling is the admin layer and the migration set.

Migration path Pin to ^1.2, never *. Install on a feature branch, diff the v1.2.4→v1.2.5 tag locally, and record the finding in the PR. Run migrations against a restored production snapshot rather than an empty database so table-name and index collisions surface before staging. Publish migrations and config into the repo so they pass through normal code review — from that point forward they are our schema, with a named owner, not an upstream artifact we happen to run.

Compatibility Check specifically for the four ways a "patch" breaks a small package: renamed config keys, changed table names, altered unique indexes, changed seeder signatures. Any of those at a patch version is a semver violation and a signal about release discipline worth escalating before we build a feature on top. Confirm the Filament major aligns with ours — that is where this family of packages usually bites.

Sequencing

1. Diff the tag and document it. Gate for everything downstream.
2. Install and migrate against a production snapshot; confirm idempotency and reversibility.
3. Seed in staging as a background job; record duration, row counts, and DB write volume.
4. Wrap all lookups behind a thin location service/repository so a future swap to a commercial provider is a one-file change.
5. Regression-test every feature that joins against location tables.
6. Deploy in a low-traffic window with a snapshot immediately prior.
7. Fold the package into the standard dependency cadence with a named owner — audit-and-merge, not automated merge.

Operational Impact

Maintenance Cost is dominated by auditing, not upgrading. Every release, however small, needs a diff read by someone who understands the schema. The mitigating factor is size: if upstream stalls, vendoring the migrations and models into the app is a few hours of work, and because this is reference data the blast radius of abandonment is genuinely low. Decide up front whether we are consumers or de facto maintainers — with 0 dependents, plan as though it is the latter and budget the internal-ownership line item accordingly.

Support Community-only: no SLA, no vendor escalation, no security-response channel. The internal runbook must capture the pinned version, seeded row counts, seed commands, refresh procedure, and rollback steps, so an on-call engineer unfamiliar with TomatoPHP can recover without upstream. Assign a named owner for geo-data freshness; "nobody" is the default and it is the wrong answer.

Scaling Read-mostly and highly cacheable: put country/state/city lookups behind a long-TTL cache, invalidated on re-seed. Index the foreign keys we add on our own tables (country_id, city_id) — the package cannot do that for us. Avoid lazy-loading hierarchical relations in list endpoints; N+1 on geo data is the classic failure. The write-side bottleneck is seeding: a full city import runs for minutes and generates meaningful WAL/binlog volume, so it is a background job, never a request path.

Failure modes

• Migration collision with pre-existing location tables; rollback dropping reference rows other features depend on.
• Seeder timeout leaving a half-populated hierarchy that returns empty results silently — a bad failure mode, because dropdowns look "broken" rather than "incomplete."
• Filament/Tomato version skew breaking the admin UI after an unrelated framework upgrade.
• Stale data surfacing as a customer-facing bug (renamed city, changed ISO code, disputed border) with no owner and no refresh path.

Ramp-up Low for an engineer comfortable with Laravel packages: hours, not days. The ramp-up that actually matters is organizational — the team must internalize that this is seed data, not source of truth, and that the migrations are first-party the moment they are published. That is a one-time alignment conversation with engineering and a standing ledger item for the TPM: pinned version, named data owner, documented refresh cadence. Get those three named in the adoption ticket and the package delivers its value — removing "design location tables, source the data, build the admin screens" from the next milestone — without inheriting silent, unowned liability.