Address Format Laravel Package

Product Decisions This Supports

• Market expansion and localized checkout. Address conventions differ per country — postal code before city in DE, prefecture instead of state in JP, no postal code at all in some markets. This package lets a PM treat "supported markets" as an explicit product decision backed by a config map rather than an engineering rewrite, and localized address display is one of the cheapest levers against cart abandonment in new markets.

• Ratifying the data model before it hardens. The package forces the right architectural conversation: persist canonical structured fields (street_address, city, state, postal_code, country_code) and format only at render time. A PM should ratify this early — a formatted address blob cannot be re-localized later when a template improves or a market is added, and unwinding that is expensive.

• Fulfillment and carrier payloads. Label printing, carrier APIs, invoice PDFs, and CRM exports all expect country-specific address shapes. Centralizing formatting gives one place to fix when a market's convention is wrong, instead of bespoke per-carrier logic scattered across jobs.

• Honest build-vs-buy scoping. "Address handling" is at least three separable products: display formatting (this package), validation/verification (paid vendor), and autocomplete (paid vendor). This package solves only the first. Naming that to stakeholders prevents anyone believing "we solved addresses" after a one-day integration, and lets you sequence a validation vendor contract behind a launch.

• Low-cost market unblock. When localized address display is a launch prerequisite, this is a plausible stopgap that defers vendor spend — provided it is treated as vendorable code with a defined owner, not a platform standard.

• Roadmap risk framing. 5 stars, zero dependents, single maintainer, BSD-2-Clause, and a 2.0.0 release that changed only coding standards and the PHP floor. That is a replaceable dependency profile, not a strategic bet. The correct PM posture is "adopt behind an interface, budget template maintenance, keep commerceguys/addressing on the bench."

When to Consider This Package

Adopt when all of these hold:

• You already ingest or capture structured address fields. The description says "parse," but the library does not parse free text — there is no "123 Main St, Springfield" → components path. If your only input is a textarea, this package does not solve your problem and you will find out mid-sprint.
• Your launch set is a handful of well-known markets (US, GB, DE, JP, etc.) whose templates you can read and validate against a real envelope in an afternoon.
• Your first surface is low-risk and high-visibility — invoice PDFs and confirmation emails — not checkout validation or shipping labels. A formatting bug there arrives as a support ticket, not a failed shipment.
• Your runtime is PHP 8.2+ on every consuming service, or you will deliberately pin ^1.x.
• Engineering will honor an adapter/contract boundary so the facade never appears in controllers or Blade.

Look elsewhere when:

• You need free-text parsing, address verification, correction, or autocomplete — buy a vendor; this does nothing there.
• You need per-locale output (a French-language invoice for a German address) or localized field labels (PLZ, 〒). The package picks a template from the country code only; form layout and labels are yours.
• You need CLDR-backed breadth, active maintenance, or community validation — commerceguys/addressing is the maintained alternative, and the migration should cost one adapter class if you built the boundary.
• Markets in scope are non-Latin or RTL (Arabic, Hebrew, Japanese) and your rendering target is PDF — visual order and line handling vary by renderer and are not guaranteed. Test the rendered artefact, not the string.
• You need a guaranteed maintenance branch or backported fixes. There is one maintainer and no stated sunset support for 1.x.

How to Pitch It (Stakeholders)

To executives: This is a small, BSD-licensed library that renders postal addresses correctly per country — the display layer only. It is the cheapest way to make a new market's invoices and confirmation emails look local, and it lets us scope "which markets do we support" as a product decision rather than an engineering project. It is explicitly not address validation or autocomplete; those remain a separate vendor decision, and I want that distinction on the record so no one thinks addresses are "done" after a one-day integration.

To engineering: Wire it behind an AddressFormatter interface on day one and never call the facade outside that adapter. That single habit converts the real risk — 5 stars, zero dependents, one maintainer — into a one-file change if we fork the config or swap to commerceguys/addressing. Confirm PHP 8.2+ before adopting (2.0.0's only breaking change is the PHP floor plus a standards refactor — capture golden output files on 1.x across all markets and require byte-identical results). Persist structured fields, format only at render. Build per-market golden-file tests; they are our regression suite, our upgrade gate, and our documentation if upstream goes quiet.

The honest caveats to state up front: the word "parse" in the description is wrong — it formats structured input and performs no key validation, so a mismatched key silently drops a line rather than throwing. Budget a small recurring allowance to review templates, because country metadata drifts and 2.0.0 shipped no refresh. And add config:cache to the deploy script — stale cached config is the cause of nearly every "template isn't taking effect" ticket.