feat(address): standardized address creation

[jure-knezovic]

Summary

Adds a standardized, type-safe, swappable way to create an address for a model. The package provides the mechanism and enforces no policy — no dedupe, no per-type uniqueness, no default/primary. An app imposes its own rules by rebinding the contract.

$user->addAddress(new AddressData(street: 'Pariser Platz 1', city: 'Berlin', country: 'de'), AddressType::Billing);
$user->addAddress(['city' => 'Berlin'], AddressType::Shipping);     // loose array accepted
$user->addAddress($placeDetails->toAddressData(AddressType::Home)); // bridge from a lookup result

// Customise creation globally with one bind:
$this->app->bind(CreatesAddresses::class, MyAddressCreator::class);

What's included

• AddressData — canonical write DTO (fromArray / withType / toArray), plus PlaceDetails::toAddressData() and PostalAddress::toAddressData() bridges so the existing DTOs converge onto one shape.
• CreatesAddresses contract + default AddressCreator service (bound singleton) — the swap point.
• HasAddresses::addAddress(AddressData|array, AddressType|string|null) — the typed entry point.
• Config::addressesRelation() — single source of truth for the polymorphic morphMany wiring (used by both HasAddresses::addresses() and AddressCreator).
• AddressType roles are now Billing / Shipping / Home / Work (Primary dropped — it conflated a default flag with a role).

No migration change.

Testing

• composer test — 119 passing (506 assertions)
• composer stan — clean at level 9, zero suppressions

New: tests/Unit/AddressDataTest.php, tests/Feature/AddressCreationTest.php (covers DTO + array paths, country uppercasing, type casting, container rebinding, and enum-disabled mode).

[Copilot]

Pull request overview

Adds a standardized, swappable address-creation flow to the package by introducing a canonical write DTO (AddressData), a container-bound creation contract (CreatesAddresses), and a typed entry point on owner models (HasAddresses::addAddress). It also centralizes the polymorphic relation wiring and extends schema.org support with a PostalAddress DTO plus model mapping.

Changes:

• Introduces AddressData (write DTO) plus bridges from existing DTOs (PlaceDetails, PostalAddress) to unify creation input.
• Adds CreatesAddresses + default AddressCreator (container binding) and exposes HasAddresses::addAddress(...) as the standard persistence entry point.
• Adds schema.org PostalAddress DTO + Address::toSchemaOrg(), updates AddressType roles, and expands docs/tests.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/Unit/PostalAddressTest.php	Adds unit coverage for schema.org PostalAddress array/JSON-LD output behavior.
tests/Unit/AddressDataTest.php	Adds unit coverage for AddressData construction, normalization, and bridge methods.
tests/Feature/AddressCreationTest.php	Adds feature coverage for addAddress() DTO/array paths, type override, enum-disabled mode, and container rebinding.
tests/Feature/AddressableTest.php	Extends feature coverage to include Address::toSchemaOrg() mapping.
src/App/Support/Config.php	Centralizes polymorphic relation wiring via Config::addressesRelation().
src/App/Services/AddressCreator.php	Adds default CreatesAddresses implementation that persists via the configured relation.
src/App/Models/Address.php	Adds toSchemaOrg() mapping to PostalAddress DTO (and model docblock properties).
src/App/Enums/AddressType.php	Updates built-in enum cases to Billing/Shipping/Home/Work (drops Primary).
src/App/Data/PostalAddress.php	Adds schema.org PostalAddress DTO with fragment + JSON-LD rendering and bridge to AddressData.
src/App/Data/PlaceDetails.php	Adds toAddressData() bridge to the canonical write DTO.
src/App/Data/AddressData.php	Adds canonical write DTO with fromArray(), withType(), and column-ready toArray().
src/App/Contracts/CreatesAddresses.php	Adds the contract used as the swap point for address creation.
src/App/Concerns/HasAddresses.php	Switches addresses() to use centralized relation and adds addAddress() entry point.
src/AddressableServiceProvider.php	Binds CreatesAddresses to the default AddressCreator implementation.
README.md	Documents standardized creation (addAddress/AddressData) and schema.org PostalAddress emission.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.