Swissstreets For Filament Laravel Package

Technical Evaluation

Basis of evaluation: No prior assessment, no package inventory data, and no source/docs were supplied. This evaluation is derived solely from the v0.8.0 release notes, so findings are directional and should be validated with a short spike before commitment.

Architecture fit: The package exposes a model-bound fluent builder — Address::cascade('address_id') returns an AddressCascade value object — which is idiomatic Laravel (service provider + facade/static entry point + chainable configuration + form components). It assumes an address_id foreign key on the host model and a normalized address registry behind it (country/region/town/street/house number). For applications already modelling addresses relationally, this is a natural fit. For applications storing addresses as flat text columns, it implies a schema migration and a backfill, which is the larger architectural cost — not the package itself.

Integration feasibility: Low for greenfield address forms. The v0.8.0 change makes the three-select cascade a first-class object with feature parity to the single-field case, which removes the previous need to hand-roll multi-step address UX on top of the package. The main integration cost is remediation, not adoption: the second positional argument of cascade() is gone, replaced by ->nonresidential(). Because PHP silently ignores surplus positional arguments on userland methods, callers of the old form will not fatal — they will simply lose the non-residential behaviour. That is a silent behavioural regression, and it is the single most important thing to grep for.

Technical risk:

• Pre-1.0 API churn. A breaking signature change at v0.8.0 confirms no compatibility guarantees across minors. Any planning assumption of "upgrade freely within 0.x" is invalid.
• Silent failure mode on upgrade. Old two-argument calls degrade quietly rather than erroring, so automated tests must cover non-residential selection specifically, not just "the form renders".
• Write path into the address registry. freetext() promotes unlisted house numbers, streets, and foreign towns into manual register rows. That turns a read-only lookup package into a data-authoring component with deduplication, normalization, and authorization implications that were previously out of scope.
• Geolocation dependency. nearMe() / near() ordering, including pre-typing on open, implies a location signal (browser geolocation or IP) plus a proximity query over the town dataset. Both introduce privacy, consent, latency, and graceful-degradation concerns.
• Dataset provenance unknown. Licensing, update cadence, coverage, and whether the registry is bundled, remote, or database-backed are all unverified. For address data this is a legal and correctness question, not a detail.

Key questions for the maintainer:

1. Is the address dataset bundled, fetched from a remote service, or read from host-owned tables? What licence and update cadence apply?
2. What is the path and timeline to 1.0, and will 0.x minors continue to carry breaking changes?
3. How are freetext() manual rows deduplicated, normalized, and authorized? Can writes be disabled or routed through an approval step?
4. What are the exact semantics and fallbacks for near() versus nearMe() when location is denied, unavailable, or slow?
5. Which Laravel/PHP versions, and which front-end stack (Blade only, Livewire, Alpine, Inertia) are supported?
6. Is the package multi-country, and how is locale/translation of address labels handled?

Integration Approach

Stack fit: The API shape (static entry point, fluent configuration, form components) reads as a conventional Laravel package with a service provider and probably Blade/Livewire-rendered selects. Confirm composer constraints against our Laravel and PHP versions before scoping — pre-1.0 packages frequently track only the two most recent Laravel majors.

Migration path: Treat v0.8.0 as an upgrade-with-remediation, not a drop-in. Sequence:

1. Inventory every cascade( call site and flag any with a second positional argument.
2. Rewrite those to the fluent form (->nonresidential()), and add a regression test per call site asserting non-residential options still appear.
3. Only then evaluate the new capabilities (nearMe(), freetext()) as net-new work.

If we are not yet on the package at all, skip step 1 and adopt the v0.8.0 API directly — the fluent object is the better foundation and avoids building on a signature that has already been retired.

Compatibility: Pin the exact patch version (0.8.0, not ^0.8) and treat every minor as a potential breaking release requiring a review of notes. No shared/composite package should depend on this at a floating constraint.

Sequencing:

1. Spike (1–2 days): install in a scratch branch, wire one form, confirm dataset source/licence and front-end requirements, answer the key questions above.
2. Decision gate: if dataset provenance or 1.0 timeline is unsatisfactory, stop — this is a dependency we would be structurally bound to for address entry.
3. Remediate and upgrade behind a feature flag, with non-residential and freetext flows explicitly tested.
4. Enable nearMe() and freetext() as separate, later releases — they carry the privacy and data-quality risk and should not be bundled into the initial rollout.
5. Backfill/validate any pre-existing free-text addresses against the registry before exposing manual-row creation to users, so we do not compound duplicates.

Operational Impact

Maintenance: Expect a real, recurring maintenance line: each 0.x minor needs a release-note review, a compatibility check, and likely a code change. Budget roughly one small upgrade task per minor until 1.0. This is acceptable for a package on a critical path only if we pin versions and keep the integration surface narrow — ideally a single wrapper/service class so call sites do not scale with the number of forms.

Support: Support model is unstated and likely maintainer-dependent (single author, community issues). Escalation path for a broken address form in production is therefore weak; we should be prepared to fork or vendor the package. That argues for keeping our integration thin enough to replace.

Scaling: Two cost centres. First, proximity ordering for nearMe()/near() — proximity queries over towns should be cached or precomputed, and the on-open call should be treated as a hot path with a timeout and a deterministic fallback ordering. Second, registry growth from freetext() manual rows — unbounded user-authored rows degrade lookup quality and select performance over time, so plan for dedupe and periodic cleanup from day one.

Failure modes to instrument:

• Silent loss of non-residential filtering after upgrade — no exception is raised; only a UI test catches it.
• Geolocation denied, blocked, or slow — must fall back to alphabetical/last-used ordering without blocking form render; verify the on-open pre-typing path does not delay first paint.
• freetext() creating duplicates or malformed registry rows — needs dedupe keys, validation, and ideally an audit trail of who created which manual row.
• Partial cascade state — user selects a manual row at step one; confirm the selected value survives all three selects, as the release notes claim, under edit and re-render.
• Dataset staleness — new-build addresses missing from the registry push users into freetext(); monitor manual-row creation rate as a data-quality signal.

Ramp-up: Moderate. The fluent API is discoverable, but the cascade is a small state machine (three dependent selects, plus a manual-entry branch that must propagate across all three), and most defects will live in the transitions rather than the happy path. Allocate time for QA on address flows specifically, and require a test that exercises the manual-register path end to end before enabling freetext() for real users.