Swissstreets For Filament Laravel Package

Product Decisions This Supports

• Checkout and onboarding address capture: Address::cascade('address_id') now exposes the same UX controls at the cascade level as the single-field version. This directly supports decisions about how much friction to accept in address entry, especially for delivery, KYC, and signup flows where bad addresses create downstream cost.
• Build vs. buy for address data and hierarchy logic: The package owns the administrative hierarchy, proximity ordering, and manual-entry fallback. That lets you avoid building and maintaining town/street datasets and cascade-selection state machines in-house.
• Conversion and completion-rate trade-offs: ->nearMe() / ->near() put the nearest towns first and load them before typing. This is a measurable UX decision: you can A/B whether proximity ordering reduces time-to-complete and abandonment versus alphabetical or static ordering.
• Address coverage policy: ->nonresidential() and ->freetext() turn “do we support commercial addresses and unlisted addresses?” into a configuration decision rather than a custom build. freetext() puts the add-address form on every step; an unlisted house number, street, or foreign town becomes a manual register row and is selected across all three selects. That is a product-level fallback path for incomplete address data.
• Roadmap and upgrade planning: v0.8.0 is a breaking change for any integration using the second positional argument of cascade(). The migration is narrow: replace that argument with ->nonresidential(). This should be scheduled as a small dependency upgrade, not treated as a redesign.
• Vendor and version risk: As a 0.x package, it can still make breaking API changes. That supports a decision to pin versions and track release notes, or to wrap the package behind an internal address-service interface if address capture is business-critical.

When to Consider This Package

• You are building Laravel/PHP applications that need hierarchical address entry in a region where town/street/house-number cascades are expected, and you want proximity ordering plus a manual fallback for unlisted addresses.
• You want non-residential addresses to be an explicit toggle rather than a separate form or custom validation branch.
• You need a maintained package to handle the cascade data and selection behavior, and you are comfortable adopting a pre-1.0 dependency with occasional breaking changes.
• You want the “unlisted address” path to create a manual register row that remains selectable across all three selects, rather than forcing users to abandon the form or enter a free-text-only address.

Look elsewhere if:

• You only need a single free-text address field, or addresses are outside the package’s covered region.
• You require authoritative postal validation, geocoding, or delivery-point verification beyond hierarchical selection.
• You cannot accept pre-1.0 breaking changes, or you need a stable public API before 1.0. In that case, either pin aggressively or wrap the package behind your own interface.
• Your address model is not a three-select cascade, or you need heavy customization of the hierarchy and data source.

How to Pitch It (Stakeholders)

For executives: This package improves address capture in checkout and onboarding by guiding users through a structured cascade, ordering nearby towns first, and allowing a manual fallback when an address is not listed. The business impact is fewer invalid addresses, less failed delivery or rework, and higher form completion. It avoids building and maintaining an address database in-house. The v0.8.0 release expands the cascade-level capabilities and includes one small breaking change: the second positional argument to cascade() is removed in favor of ->nonresidential(). Migration effort is low.

For engineering: Adopt as a Laravel package with a fluent API. v0.8.0 makes AddressCascade feature-equivalent to the single-field API: proximity ordering, non-residential filtering, and freetext manual registration across all three selects. The breaking change is contained: replace the removed second positional argument with ->nonresidential(). Because the package is pre-1.0, pin the version and review release notes on upgrade; consider an internal adapter if address entry becomes a critical path.