- How do I install adamlc/address-format in a Laravel app?
- Install it with composer require adamlc/address-format. There is no service provider, config file, facade, or migration to register, so it works identically on Laravel 10, 11, and 12. Just confirm the PHP constraint in its composer.json matches your lowest supported runtime, which is PHP 8.1 or 8.2 depending on your Laravel version.
- Does adamlc/address-format parse free-text addresses?
- No. Despite the description mentioning parsing, this is a formatter: it takes already-separated components such as house number, road, locality, postcode, and ISO country code and renders them into a country-specific template. It does not parse unstructured input, validate, normalize, or geocode. If you need to clean up user-typed addresses, pair it with a validation or parsing service and use this package only for final rendering.
- Should I call adamlc/address-format directly from Blade views, mailables, or jobs?
- You can, but you should not. Define a thin AddressFormatter contract in your application, implement it with an adapter over the vendor class, bind it in the container, and route every address assembly call site through it. That keeps the vendor namespace out of domain code, makes the library swappable, and lets you test formatting without touching the package.
- Which countries does adamlc/address-format support and what happens for an unsupported country code?
- The package ships a hand-curated dataset of country layouts, so coverage varies by market. List the destination countries your app must render and verify each one against a real fixture address before launch. Decide explicitly what happens on an uncovered ISO code, whether that is an empty string, a generic fallback layout, or an exception, rather than letting output degrade silently. Also confirm the provenance and licensing of the data tables, since the MIT license covers the code, not necessarily the bundled data.
- Where should the country code passed to the formatter come from?
- Pass ISO 3166-1 alpha-2 codes taken from the address record's own country field, not from the request locale. Request locale describes the user's language, not where the mail piece is going, and mixing the two produces plausible-looking but wrong labels. Enforce UTF-8 end to end so non-Latin scripts render correctly and stay consistent across HTML, plain-text, and label printing surfaces.
- Does adamlc/address-format validate addresses or do geocoding and postcode lookups?
- No. It performs no validation, normalization, geocoding, or postcode lookup, and it makes no network calls or filesystem reads. If you already use a commercial address validation vendor, keep it upstream and let this package own only the final rendering step. Do not duplicate validation logic inside your formatter adapter.
- How should I test address formatting before shipping it to production?
- Build a fixture set of real production addresses for your top five markets and assert the exact rendered output, including whitespace and line breaks. Snapshot tests catch silent regressions, which matter here because bad formatting still looks plausible and ships to labels and order confirmations. Add explicit cases for apartment or unit lines, PO boxes, rural routes, building names, and both multi-line and single-line rendering.
- Is adamlc/address-format safe to depend on in production?
- Runtime risk is low: the library is small, stateless, dependency-free, and does no IO. The maintenance risk is higher, with a small star count, effectively a single maintainer, and no SLA or security response process. The code is MIT licensed, but verify the data licensing separately, and confirm you could fork or vendor the country format tables cleanly if maintenance stalls.
- Can adamlc/address-format produce multi-line output for shipping labels?
- Rendering mode matters, because HTML confirmations, plain-text emails, and label printers each have different expectations for line breaks and whitespace. Have your adapter return an array of lines and join them per surface rather than embedding vendor output directly. Test against your actual label printer, since trailing whitespace and CRLF differences only show up there.
- Is adamlc/address-format a replacement for an address validation service, and what are the alternatives?
- No, it is one component in a larger address pipeline. Use a commercial validation or parsing provider for input quality and let this package handle only localized output. Alternatives include maintaining your own country template map, using a locale-aware formatting helper, or relying on country data bundled with a carrier SDK; the real value here is the curated templates, so evaluate it against your specific country list.