Address Format Laravel Package

Technical Evaluation

Architecture fit. This is a presentation-layer utility, not a domain service. It maps a structured address (street, locality, administrative area, postal code, country) plus a country code onto a localized string using a config-driven template table. That is a narrow, stateless, side-effect-free function — which is exactly what you want in a formatter. It fits cleanly behind an interface (AddressFormatter) with a thin adapter wrapping the facade, and it must not leak into controllers, models, or Blade. The correct architectural decision it reinforces is bigger than the package: persist canonical structured columns and format only at render/print time. That schema decision is a PM-ratifiable choice and is far cheaper now than after the schema hardens around a display blob.

Integration feasibility. Low effort, low ambiguity. composer require, vendor:publish, read config/address-format.php, pass an array, get a string. The README example is effectively the entire API surface — there is no deep integration to design. Realistic cost: half a day for a developer to get first output, one to two days to do it properly (contract, value object, adapter, golden-file tests, Blade component). The work is not the integration; the work is the discipline around it.

Technical risk. The risks are concentrated and mostly organisational, not technical:

• The description is wrong where it matters. "Parse" implies free-text → structured components. It does not parse. If any ingestion path is a single textarea, this package does not solve it, and the gap surfaces mid-sprint. Confirm structured fields exist upstream before committing.
• Silent misformatting is the native failure mode. No key validation. A renamed column or mismatched array key is a missing line, not an exception. That produces a deliverable-looking label that fails downstream — worse than an error.
• Abandonment. 5 stars, 0 dependents, single maintainer, score 0.325. Zero dependents means no ecosystem validation whatsoever. BSD-2-Clause makes forking legitimate and trivial, which is the mitigation — but only if you vendor the templates deliberately.
• Static data drift. Country metadata (postal patterns, subdivision naming) changes. 2.0.0 shipped no metadata refresh. Nobody upstream is contractually watching your markets.
• 2.0.0 is breaking with no functional change — coding standards plus a PHP 8.2 floor. There is no feature reason to upgrade; the runtime should gate it.
• Scope adjacency is not scope. Formatting ≠ validation/verification ≠ autocomplete. This package answers only the first. A stakeholder must not conclude "addresses are solved" after a one-day integration.

Key questions for the team.

1. Which markets are in scope at launch, and has anyone read the config templates for each of them against a real envelope?
2. Does every ingestion path already produce structured fields, or is there free-text we are quietly assuming this library handles?
3. Which service owns template patches when a market's convention is wrong — and who is named as that owner if upstream goes quiet?
4. What is the PHP floor per consuming service, and are any of them still on 8.1 (forcing a deliberate ^1.x pin with a recorded sunset expectation)?
5. What is the explicit fallback for an unsupported country code — and does it log, or does it guess?
6. Is address validation/verification scoped separately with its own (vendor) budget, or is this package being positioned as the whole answer?
7. Are we testing the rendered artefact (PDF) or only the string? Non-Latin and RTL output can be a correct string in a wrong-looking document.
8. Has the BSD-2-Clause attribution requirement been cleared with legal?

Integration Approach

Stack fit. Native Laravel: service provider, facade, publishable config. It presumes a modern PHP runtime (8.2+ for 2.x) and a standard Laravel config-cache deploy. It has no database, queue, or cache dependencies, so it drops into any Laravel service without touching infrastructure. The only genuine coupling is the config file — which is the product.

Migration path. There is no data migration; the migration is a schema discipline migration. Move from hardcoded string concatenation in views and PDF templates to: structured columns → Address value object → AddressFormatter contract → adapter → facade. Bind in a service provider and never reference AddressFormat:: outside the adapter. That single habit converts the abandonment risk from an open question into a one-file swap to commerceguys/addressing if CLDR-backed coverage or active maintenance later becomes a requirement. Cost of that resistance: about an hour. Cost of skipping it: a codebase-wide search-and-replace plus re-test.

Compatibility considerations.

• Pin explicitly (^2.0 or 2.0.*) per service; do not let the resolver choose. Any service that cannot reach PHP 8.2 gets a deliberate ^1.x pin and a documented sunset — there will be no maintenance branch and no backported fixes.
• Config caching is the most likely operational bug. Overriding a template means config:cache must re-run in deploy. Put it in the deploy script explicitly; a "template not taking effect" report is almost always stale cached config.
• The package formats by country code, not locale, and does not supply field labels. Localized label text, form layout, and language selection are yours.
• Carrier APIs generally want structured fields, not a concatenated string. Use the formatter for the human-readable label and confirmation; pass structured fields to the carrier. Keep any per-carrier string formatting inside the adapter, not scattered across jobs.
• PDF renderers (DomPDF, wkhtmltopdf, Browsershot) each handle RTL and line-breaking differently. Validate against the actual document.

Sequencing.

1. Confirm the PHP floor on every consuming service; resolve pins before any code.
2. Read config/address-format.php for launch markets (US, GB, DE, JP at minimum) and validate line order, separators, and which components appear at all against brand and carrier expectations. Wrong template = config override, never a code change.
3. Spike 3–5 real sample addresses per market, eyeball against a real envelope, commit outputs as golden files. These become the regression suite, the 2.0.0 upgrade gate, and the documentation when upstream goes quiet.
4. Build the contract, value object, adapter, and Blade component.
5. Ship to invoice PDFs and confirmation emails first — low-risk, high-visibility, and a bug is a support ticket rather than a failed shipment.
6. Only then extend to checkout display and shipping labels, with explicit unsupported-country logging and a conservative fallback.
7. Scope validation/verification and autocomplete as a separate track with separate vendor budget.

Operational Impact

Maintenance. Single maintainer, low stars, zero dependents, sporadic releases. Treat the template config as vendored data, not as an upstream responsibility. Budget a small recurring allowance (roughly a half-day per quarter for a modest market set) to review and patch templates for markets you actually serve. Decide and record now who owns that patch. Because the licence is BSD-2-Clause, forking the config — or the whole library — is legitimate and cheap; make that the documented contingency rather than a scramble.

Support. There is no vendor. Support is internal by definition. That means: named owner, an ADR recording why this package was chosen over commerceguys/addressing, golden fixtures checked in, and a runbook note that the PHP floor changed at 2.0.0 so nobody later downgrades the package to fit an older runtime.

Scaling. Runtime cost is negligible — pure string assembly, no I/O. The two scaling concerns are both code-level, not load-level:

• An Eloquent accessor that resolves the container and formats on every attribute access will bite inside loops over hundreds of orders. Eager-compute and cache on the model instance, or drop the accessor in favour of explicit formatting at the render boundary.
• Config cache is a deploy-time dependency, so template changes require a deploy — not a data update. That is fine, but it must be in the runbook or a market addition will silently not ship.

Failure modes to instrument.

• Silent misformatting — a missing city or postcode for one market only, doubled or trailing separators where a component is null, a US-looking address on a DE invoice. Mitigate with the value object, per-country required_if validation upstream, and golden-file tests. Do not expect the library to complain.
• Unsupported country guessed — a plausible-but-wrong template produces a deliverable-looking label that fails downstream. Require an explicit branch that logs and falls back rather than letting the package infer.
• Stale config cache — template override present in repo, absent in production.
• Render-artefact failure — correct string, wrong PDF, for RTL or non-Latin scripts.
• Template drift — the market changes, the vendored template does not.

The package will never tell you it produced bad output, so the real monitor is downstream: undeliverable shipments, failed address verification, and support tickets mentioning address errors. Wire those to a dashboard before the second market goes live.

Ramp-up. Very shallow. A mid-level Laravel developer is productive in under a day; the package's entire conceptual surface is one function and one config file. The learning investment is not in the library but in the surrounding discipline — adapter boundary, value object, golden fixtures, explicit fallback — which is one to two days and is transferable to whatever replaces this package.

TPM position. Treat this as a low-cost stopgap or vendorable code sample that unblocks localized address display for a market launch, not as a platform standard. Ratify the structured-schema decision alongside it, keep the adapter boundary non-negotiable, and keep commerceguys/addressing on the bench. The opportunity score (21.58) and 0.325 composite are consistent with that framing: cheap to adopt, cheap to abandon, and not something to build a roadmap on.