Address Formatter Bundle Laravel Package

Getting Started

This is a v1.0-alpha package that formats a postal address according to the conventions of the destination country's national post operator. It ships an Address entity (a value object holding recipient name, street lines, locality, administrative area, postal code and country) and a formatter that renders it to a postal-correct string.

Minimal path:

1. composer require the package (expect an alpha stability flag: "minimum-stability": "alpha" or composer require pkg/name:^1.0@alpha).
2. Publish the config if the package offers it (php artisan vendor:publish --tag=...) — you will almost certainly need to confirm the default country/fallback behaviour and the line separator.
3. Look first at the Address entity constructor/factory and the formatter entry point (typically Address::format() or a Formatter::format(Address $address)). Read the bundled test suite's fixtures — for a formatting package the test dataset is the documentation.
4. First use case: format an address for a single known country in a Blade view or an API resource.

$address = new Address(
    name:       'Jane Doe',
    street:     ['123 Main St', 'Apt 4'],
    locality:   'Springfield',
    region:     'IL',
    postalCode: '62704',
    country:    'US',
);

echo $address->format(); // "Jane Doe\n123 Main St\nApt 4\nSpringfield, IL 62704\nUNITED STATES"

Start with two or three countries you actually ship to (e.g. US, GB, JP) rather than assuming global coverage — the alpha status makes breadth of country rules the main unknown.

Implementation Patterns

Keep storage structured, format at the edges. Persist the address as discrete columns or a JSON column (street_lines, locality, region, postal_code, country_code). Call the formatter only when producing output — mail merges, PDFs, confirmation emails, shipping labels. Never store the formatted string as the source of truth; formatting rules and the country's post operator conventions change.

Wrap it in your own formatter service. Rather than calling the package directly from Blade, bind a thin AddressFormatter of your own:

class AddressFormatter
{
    public function __construct(private Formatter $formatter) {}

    public function line(AddressContract $a): string
    {
        return $this->formatter->format($this->toEntity($a));
    }
}

This gives you one place to add caching, fallback formatting, and a swap-out point if the alpha package stalls.

Hydrate from Eloquent with a toAddressEntity() method. Put the mapping on the model so controllers, resources and mailables all produce the same entity.

Use API Resources for presentation. new AddressResource($order->shipping_address) keeps the formatted block out of your domain layer and gives you a stable JSON shape (lines, formatted, country) for front-ends that want to render their own layout.

Localize deliberately. Country of the recipient drives the format, not the locale of the viewer. A German customer viewing your English site still gets a German-formatted address. Pass the country explicitly; never let it default from app()->getLocale().

Mailables and PDFs are the highest-leverage integration: override Mailable::envelope()/content() view data with the formatted block so the letter body and the mailing label agree.

Test with a country dataset. Build a Pest/PHPUnit dataset keyed by ISO country code with expected multi-line output. This doubles as your coverage check — you will quickly discover which countries the package handles and which fall through.

Custom/unsupported countries: if the package exposes a formatter registry or config-driven templates, register your own rule for the countries you need rather than post-processing with string concatenation.

Gotchas and Tips

• Alpha stability. Expect API churn between 1.0-alpha and stable. Pin the exact version (1.0.0-alpha or dev-main#<sha>), and isolate all calls behind your own service (see above) so a breaking rename is a one-file fix.
• Coverage is unknown from the release notes. The notes point at a third-party reference chart rather than listing supported countries. Enumerate supported ISO codes from the source/config and assert them in a test; add a sensible fallback format (name / street / locality / region / postcode / country) for anything missing.
• Field ordering is not universal. Japan puts the postal code first and the recipient name last; the US puts the state and ZIP on the locality line; some countries omit the region entirely. Never hand-roll implode("\n", ...) "just for now" — that is exactly what this package exists to prevent.
• Country name vs country code. Many formatters expect an ISO 3166-1 alpha-2 code and emit the country name in the destination language (or upper-cased, per UPU convention). Pass the code, let the package render the name, and don't double-append your own country label.
• Line separators and trailing newlines. Windows/PCL label printing may need \r\n. Check whether the config exposes a separator and whether format() returns a trailing newline — that trailing byte will bite you in assertEquals and in PDF cell layout.
• Postal code normalization. UK and Canadian codes are conventionally upper-cased with a single space; Dutch and Portuguese codes have their own spacing rules. If the package doesn't normalize, do it before constructing the entity — garbage in, garbage out.
• Diacritics and transliteration. Shipping carriers and some label printers require ASCII transliteration. A formatted output with correct accents can still fail downstream; check whether the package offers a transliteration/ASCII mode before writing your own iconv pass.
• Empty optional fields. A missing region or second street line should collapse the line, not emit a blank line or an orphaned comma. Assert this explicitly with sparse addresses — it is the most common formatting bug.
• Debugging: dump the entity (not the string) when output looks wrong. If the formatted result is identical across two countries, the formatter probably didn't receive the country at all — a silent fallback, not a bug in the rules.
• Extension points to look for: formatter registry / per-country rule classes, config-published templates, and a Country enum or value object. If none exist, treat the package as format-only and keep your own template layer alongside it.
• Do not use it for parsing. The notes describe a one-way formatting entity. Free-text address parsing and validation are different problems; keep using your existing validation rules for input and reserve this package for output.