Address Laravel Package

Product Decisions This Supports

• Checkout & fulfillment scope: Whether to model shipping and billing addresses as first-class value objects versus free-text fields on an order. This package gives you a ready-made shape (street, postal code, city, country) to support decisions like "do we support separate ship-to/bill-to?", "do we store address history per order?", or "do we need structured addresses for carrier rate calculation?"
• Invoice & compliance requirements: Structured addresses are a prerequisite for tax calculation, VAT/GST validation, e-invoicing formats, and invoice PDF generation. If the roadmap includes EU/UK/APAC selling, this is a data-model decision you need to make before the first invoice is issued, because migrating free-text addresses later is painful.
• Build vs. buy: The scope is small enough to be a "build" candidate (a handful of properties plus toArray/fromArray). The real decision is not "can we write this?" but "do we want to own the shape, or adopt an existing value object and keep our domain model consistent with the rest of the stack?"
• Ecosystem consistency: If your codebase already uses amethyst/* packages (collections, data, etc.), adopting amethyst/address keeps value objects interoperable and reduces the number of bespoke DTO conventions your team must learn. If you are not on Amethyst, this argument does not apply.
• Address book / CRM / KYC features: Any feature where a person or organization "can be found or communicated with" — customer profiles, multi-address books, delivery zones, fraud checks that compare billing vs. shipping — benefits from a single canonical address type rather than per-feature schemas.
• Roadmap risk assessment: Zero dependents and two stars is a signal to decide early whether this is a dependency or a starting point. That decision (adopt, vendor/fork, or reimplement) should be made explicitly rather than drifting into an implicit dependency.
• Serialization and API contract: The package gives you array/JSON round-tripping for an address. That supports decisions on API payload shape ({street, postal_code, city, country}) that affect frontend forms, mobile clients, and partner integrations.

When to Consider This Package

Consider adopting when all of the following hold:

• You already use the Amethyst ecosystem (amethyst/collections, amethyst/data, or similar) and want address to behave consistently with your other value objects.
• You need a minimal, framework-agnostic address value object — fields plus basic equality/serialization — and nothing more.
• Your address requirements are simple and single-format (e.g., a B2B product sold in one or two countries where a flat street/city/postal/country shape is acceptable).
• You are comfortable with a low-adoption, single-maintainer, MIT-licensed dependency and have a plan (pin the version, or vendor the code into your repo) if it goes stale.
• You want to avoid writing and documenting your own DTO for a concept that is genuinely commodity.

Look elsewhere when any of these apply:

• You need country-specific address formats, validation, or normalization (address parsing, postal code validation, administrative area rules). Use commerceguys/addressing or Google's libaddressinput data instead; this package does not provide that.
• You need geocoding, autocomplete, or address verification — those are external services (Google Places, Loqate, Smarty), not value objects.
• You expect Laravel-native integration (service provider, config publishing, Eloquent casts, validation rules). This is framework-agnostic PHP; you would write the cast and validation yourself.
• Your domain needs richer semantics than a flat record: multiple address types with validity periods, geo coordinates, delivery instructions, contact phone/email attached to the address, or per-country required-field rules.
• You have a strict dependency policy (security review, maintenance SLA, minimum stars/adoption thresholds). Two stars and zero dependents will not pass most such gates, and that is a legitimate reason to copy the ~100 lines into your own namespace instead.
• You are PHP-version sensitive: confirm the required PHP version and whether the package is actively tagged for current PHP releases before committing.

How to Pitch It (Stakeholders)

For executives (the one-paragraph version): Addresses are a small but structurally important part of our product: they drive shipping cost, tax, invoicing, and fraud checks, and they are expensive to change later once they are embedded in orders and invoices. amethyst/address is an MIT-licensed, dependency-free PHP value object that gives us a standard address shape for free. It is tiny and low-risk in code, but it is also very low-adoption (two stars, no dependents, single maintainer), so my recommendation is to treat it as a reference model, not a strategic dependency: adopt it if we are already standardized on the Amethyst family, otherwise vendor the small amount of code into our own domain layer. Either way, we get a structured address type now — which unblocks international shipping, tax, and invoicing — without a procurement or licensing conversation.

For engineering (the practical version): It is a plain value object — street, postal code, city, country — with array serialization and no framework coupling, no service provider, no migrations, no validation layer. Integration cost is one Eloquent cast and one FormRequest rule; both are ours to write. Upside: consistent, immutable address type across order, customer, and invoice models, and no bespoke DTO to document. Downside: no country-format handling, no validation, and no meaningful community to absorb bugs. Mitigation: pin the version, wrap it behind our own Address interface so we can swap in commerceguys/addressing if international requirements grow, and keep an eye on the upstream repo. If we are not on Amethyst elsewhere, copying the class into App\Domain costs an hour and removes the dependency entirely — that is the option I would default to unless ecosystem consistency argues otherwise.