Address Laravel Package

Technical Evaluation

What the package actually is. konekt/address is a data-model package, not a geo service. It ships Eloquent models, migrations, and seeders for Country, Province, City, Address, Person, Organization, and Location, plus an address-type concept (billing/shipping/etc.) and a polymorphic addressable relation so any domain object can own addresses. The value is the schema, the country/province reference dataset, and the addressable pattern — not runtime behavior.

Architecture fit. The package is built on Concord, Konekt's module/model-registry layer. That is the single most important architectural fact: adopting it means adopting Concord's conventions (contracts resolved through a module registry, models swappable via config) in at least the parts of the app that touch addresses. If the codebase already uses Konekt packages (konekt/user, konekt/customer, Concord itself), fit is high and near-frictionless. In a clean or conventionally-structured Laravel app, Concord is an extra indirection layer your team must learn for a peripheral domain — a real cost for a countries/provinces table.

Integration feasibility. Low-to-moderate technical effort, moderate organizational effort. Install is standard Composer + publish migrations/config. The realistic work is: (1) deciding whether to use the bundled Person/Organization models or only Address — most teams only want the address half and should not adopt the people/org half; (2) seeding and refreshing country/province data; (3) populating cities, which ships effectively empty — there is no global city dataset included, so city-level autocomplete requires you to source, license, and load your own data (GeoNames, GeoNames-based commercial feeds, or a vendor API); (4) postal-code/address validation, which the package does not do — you still need a validator (e.g., commerceguys/addressing + symfony/intl) for format rules and normalization.

Technical risk. Concentrated and identifiable:

• Adoption/bus-factor risk. ~20 stars, zero dependents, effectively a single-vendor (ArtKonekt) package. High bus factor, low external bug pressure, slow response to Laravel major releases. Score 0.31 is consistent with "works, but you are close to the only user."
• Laravel version lag. Verify the supported Laravel/PHP matrix against your target version before committing; Concord version constraints are the usual blocker, and a Concord upgrade can cascade across every Konekt package you use.
• Data staleness. Country/province lists are snapshots. No published refresh cadence; you own re-seeding and diffing.
• Coverage gaps. Province/state coverage is uneven across countries; treat provinces as best-effort and design the UI to allow free-text fallback where the list is empty.
• Scope creep. The Person/Organization models invite teams to model identity data in a package table rather than their own domain — a migration trap later.

Key questions for the maintainer / spike.

1. Which Laravel and PHP versions are supported today, and what is the stated policy for new Laravel majors?
2. Which countries have province data, and what is the source/license of that dataset?
3. Is Concord strictly required, or can the address models be consumed standalone (published migrations + plain Eloquent)?
4. Is cities intentionally empty, and is there a recommended data loader?
5. Are country names/province names translatable, and how (native names vs. ICU)?
6. Any address normalization/validation hooks, or is that explicitly out of scope?

Verdict. Adopt wholesale only if you are already in the Konekt/Concord ecosystem and your address needs are simple (country/province dropdowns, billing/shipping records). Otherwise, cherry-pick: take the schema shape and the addressable pattern, and pair commerceguys/addressing with your own thin tables. The package is small enough to imitate and too small to depend on uncritically.

Integration Approach

Stack fit. Composer-installable Laravel package; assumes Eloquent, migrations, and Concord's service-provider bootstrapping. It is not framework-agnostic and has no headless API surface — it is a persistence layer you expose yourself. No queue, cache, or external service dependencies, which is a genuine plus.

Migration path (recommended sequencing).

1. Spike (1–2 days, timeboxed). In a throwaway branch on the target Laravel version: install, publish, migrate, seed, create one address against one addressable model, render a country/province cascade. This resolves the version-matrix and Concord-fit questions empirically. Stop here if Concord fights your app.
2. Decide the boundary. Explicitly scope to Address + Country/Province (+ City only if you have a data source). Disable or ignore Person/Organization unless you have a named owner for that domain.
3. Schema first, package second. If you go with the package, publish and own the migrations immediately (vendor:publish), pin the version in composer.json, and record the decision in an ADR. Never rely on the package's migrations running implicitly in a way you can't audit.
4. Data load. Import countries/provinces via seeder in a dedicated, idempotent, re-runnable command; add a geo:sync task so future dataset updates are a deploy step, not a surprise migration.
5. Wire the addressable relation. Add the morph map entries (Relation::enforceMorphMap) and update every model that should own addresses. Do this before building UI so the polymorphic keys are stable.
6. UI and validation layer. Country select → province select (async, with graceful degradation to free text) → postal code validated by a real validator, not by the package.
7. Backfill. If migrating from existing free-text address columns, write a mapping script with a manual-review queue for unresolvable countries/provinces; do not auto-guess.

Compatibility and exit. Keep the package behind your own AddressRepository/service boundary and reference the package's contracts, not its concrete models, in your domain code. That way, if the package is abandoned, you swap implementations without rewriting call sites — Concord's contract indirection helps here, and it costs you almost nothing to preserve.

Operational Impact

Maintenance. Low runtime maintenance, non-trivial version maintenance. The tables are near-static reference data plus per-user address rows; there is nothing to tune. The maintenance burden is dependency management: a package with one maintainer and zero dependents will not track Laravel releases on your schedule. Budget for the possibility that you fork it — small surface area, MIT license, so forking is cheap and should be a pre-approved fallback, not a crisis.

Support. No vendor SLA, no commercial support, community-issue-only. Escalation path is "read the source" (feasible — it's small) or "fork it." Assign an internal owner for the address domain so there is a named person, not a team, accountable.

Scaling. Effectively free. countries/provinces are a few thousand rows; read-heavy, cache the full country list in the app cache or a config file and you remove the query entirely. Addresses scale linearly with users — ordinary indexed tables. The only scaling concern is UI: never load all cities; use typeahead against a properly indexed table or an external geocoder.

Failure modes to design against.

• Missing province data → user cannot complete checkout. Mitigation and requirement: free-text fallback and "state/region not listed" path.
• Empty cities table → broken autocomplete after launch. Mitigation: feature-flag city-level autocomplete; ship country/province first.
• Laravel/Concord upgrade deadlock → you are blocked on a third party for a security patch. Mitigation: contract boundary + pre-approved fork plan.
• Orphaned addresses on parent delete → polymorphic relations don't cascade. Mitigation: model observers or a scheduled cleanup.
• Duplicate/unnormalized addresses → poor dedupe and bad analytics. Mitigation: normalization at write time, not read time.
• Seeding in production → partial or duplicated geo data. Mitigation: idempotent upserts keyed on ISO codes.

Ramp-up. One developer-day for a Laravel-fluent engineer to be productive; add half a day for Concord's model-resolution conventions if the team hasn't used Konekt packages. Documentation is thin — plan on source reading. The Person/Organization half roughly doubles the surface area to learn, which is another argument for scoping it out.

Overall. A reasonable schema with a heavy framework dependency and thin community. Operational cost is low if you contain the blast radius; the real risk is strategic — betting address handling on a 20-star package whose maintainer's release cadence you don't control. Contain it behind an interface, own the migrations, own the data, and it's a fine choice. Skip that discipline and it becomes a quiet liability.