From f03c61141f336e8c4d2ffe44a4f2dce7e4786225 Mon Sep 17 00:00:00 2001
From: Jure Knezovic <jknezovic@byte5.de>
Date: Fri, 19 Jun 2026 11:54:23 +0200
Subject: [PATCH 1/4] feat(schema.org): add PostalAddress DTO with schema.org
 support

Introduce `PostalAddress` data transfer object to standardize schema.org postal address representation. Added `toArray` and `toJsonLd` methods for rendering address data as fragments or standalone JSON-LD. Updated the `Address` model with a `toSchemaOrg` method to generate `PostalAddress` instances. Includes tests and documentation updates.
---
 README.md                         | 26 +++++++++++++
 src/App/Data/PostalAddress.php    | 46 +++++++++++++++++++++++
 src/App/Models/Address.php        | 24 ++++++++++++
 tests/Feature/AddressableTest.php | 24 ++++++++++++
 tests/Unit/PostalAddressTest.php  | 62 +++++++++++++++++++++++++++++++
 5 files changed, 182 insertions(+)
 create mode 100644 src/App/Data/PostalAddress.php
 create mode 100644 tests/Unit/PostalAddressTest.php

diff --git a/README.md b/README.md
index 1e5fd40..a9b4be6 100644
--- a/README.md
+++ b/README.md
@@ -189,6 +189,32 @@ The columns map to [schema.org/PostalAddress](https://schema.org/PostalAddress):
 `latitude` / `longitude` are stored as `decimal(10,8)` / `decimal(11,8)` and cast
 to `decimal:8`.
 
+### Emitting a `PostalAddress`
+
+`$address->toSchemaOrg()` returns a `PostalAddress` DTO that renders to either a
+PHP array or a JSON-LD string:
+
+```php
+$address->toSchemaOrg()->toArray();
+// [
+//     '@type' => 'PostalAddress',
+//     'streetAddress' => 'Pariser Platz 1',
+//     'postalCode' => '10117',
+//     'addressLocality' => 'Berlin',
+//     'addressCountry' => 'DE',
+//     // null fields omitted; no '@context'
+// ]
+
+$address->toSchemaOrg()->toJsonLd();
+// {"@context":"https://schema.org","@type":"PostalAddress","streetAddress":"Pariser Platz 1",…}
+```
+
+`toArray()` is a **fragment** (`@type`, no `@context`) — nest it inside a parent
+entity such as `Organization`/`Person`. `toJsonLd()` is a **standalone** document
+(includes `@context`) — drop it straight into a `<script type="application/ld+json">`
+tag. Latitude/longitude are intentionally excluded, since a schema.org
+`PostalAddress` has no geo property (those belong on a `Place.geo`).
+
 ## Form validation rules
 
 Three Laravel validation rules ship for validating address input (e.g. in a
diff --git a/src/App/Data/PostalAddress.php b/src/App/Data/PostalAddress.php
new file mode 100644
index 0000000..8172262
--- /dev/null
+++ b/src/App/Data/PostalAddress.php
@@ -0,0 +1,46 @@
+<?php
+
+namespace Byte5\Addressable\App\Data;
+
+readonly class PostalAddress
+{
+    public function __construct(
+        public ?string $street = null,
+        public ?string $extra = null,
+        public ?string $postal = null,
+        public ?string $city = null,
+        public ?string $region = null,
+        public ?string $country = null,
+    ) {}
+
+    /**
+     * schema.org PostalAddress as a nestable fragment (`@type`, no `@context`).
+     * Null fields are omitted.
+     *
+     * @return array<string, string>
+     */
+    public function toArray(): array
+    {
+        return array_filter([
+            '@type' => 'PostalAddress',
+            'streetAddress' => $this->street,
+            'extendedAddress' => $this->extra,
+            'postalCode' => $this->postal,
+            'addressLocality' => $this->city,
+            'addressRegion' => $this->region,
+            'addressCountry' => $this->country,
+        ], fn (?string $value): bool => $value !== null);
+    }
+
+    /**
+     * Standalone JSON-LD document (includes `@context`), ready for a
+     * `<script type="application/ld+json">` tag.
+     */
+    public function toJsonLd(): string
+    {
+        return json_encode(
+            ['@context' => 'https://schema.org'] + $this->toArray(),
+            JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE,
+        );
+    }
+}
diff --git a/src/App/Models/Address.php b/src/App/Models/Address.php
index 37c5e4b..793a555 100644
--- a/src/App/Models/Address.php
+++ b/src/App/Models/Address.php
@@ -3,12 +3,21 @@
 namespace Byte5\Addressable\App\Models;
 
 use Byte5\Addressable\Database\Factories\AddressFactory;
+use Byte5\Addressable\App\Data\PostalAddress;
 use Byte5\Addressable\App\Support\Config;
 use Illuminate\Database\Eloquent\Casts\Attribute;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\MorphTo;
 
+/**
+ * @property string|null $street
+ * @property string|null $extra
+ * @property string|null $postal
+ * @property string|null $city
+ * @property string|null $region
+ * @property string|null $country
+ */
 class Address extends Model
 {
     /** @use HasFactory<AddressFactory> */
@@ -62,6 +71,21 @@ public function addressable(): MorphTo
         );
     }
 
+    /**
+     * The address as a schema.org PostalAddress DTO.
+     */
+    public function toSchemaOrg(): PostalAddress
+    {
+        return new PostalAddress(
+            street: $this->street,
+            extra: $this->extra,
+            postal: $this->postal,
+            city: $this->city,
+            region: $this->region,
+            country: $this->country,
+        );
+    }
+
     /**
      * @return array<string, string>
      */
diff --git a/tests/Feature/AddressableTest.php b/tests/Feature/AddressableTest.php
index 0484813..1ecf995 100644
--- a/tests/Feature/AddressableTest.php
+++ b/tests/Feature/AddressableTest.php
@@ -1,6 +1,7 @@
 <?php
 
 use Byte5\Addressable\App\Models\Address;
+use Byte5\Addressable\App\Data\PostalAddress;
 use Byte5\Addressable\App\Enums\AddressType;
 use Byte5\Addressable\Tests\Fixtures\CustomAddress;
 use Byte5\Addressable\Tests\Fixtures\CustomAddressType;
@@ -123,3 +124,26 @@
 
     expect($address->fresh()->type)->toBe('anything');
 });
+
+it('builds a schema.org PostalAddress from the model', function() {
+    $address = new Address([
+        'street' => 'Pariser Platz 1',
+        'extra' => 'Apt. 5',
+        'postal' => '10117',
+        'city' => 'Berlin',
+        'region' => 'Berlin',
+        'country' => 'de',
+    ]);
+
+    expect($address->toSchemaOrg())
+        ->toBeInstanceOf(PostalAddress::class)
+        ->and($address->toSchemaOrg()->toArray())->toBe([
+            '@type' => 'PostalAddress',
+            'streetAddress' => 'Pariser Platz 1',
+            'extendedAddress' => 'Apt. 5',
+            'postalCode' => '10117',
+            'addressLocality' => 'Berlin',
+            'addressRegion' => 'Berlin',
+            'addressCountry' => 'DE',
+        ]);
+});
diff --git a/tests/Unit/PostalAddressTest.php b/tests/Unit/PostalAddressTest.php
new file mode 100644
index 0000000..0cc5108
--- /dev/null
+++ b/tests/Unit/PostalAddressTest.php
@@ -0,0 +1,62 @@
+<?php
+
+use Byte5\Addressable\App\Data\PostalAddress;
+
+it('maps fields to schema.org PostalAddress keys', function () {
+    $address = new PostalAddress(
+        street: 'Pariser Platz 1',
+        extra: 'Apt. 5',
+        postal: '10117',
+        city: 'Berlin',
+        region: 'Berlin',
+        country: 'DE',
+    );
+
+    expect($address->toArray())->toBe([
+        '@type' => 'PostalAddress',
+        'streetAddress' => 'Pariser Platz 1',
+        'extendedAddress' => 'Apt. 5',
+        'postalCode' => '10117',
+        'addressLocality' => 'Berlin',
+        'addressRegion' => 'Berlin',
+        'addressCountry' => 'DE',
+    ]);
+});
+
+it('omits null fields from the array fragment', function () {
+    $address = new PostalAddress(
+        street: 'Pariser Platz 1',
+        city: 'Berlin',
+    );
+
+    expect($address->toArray())->toBe([
+        '@type' => 'PostalAddress',
+        'streetAddress' => 'Pariser Platz 1',
+        'addressLocality' => 'Berlin',
+    ]);
+});
+
+it('never includes @context in the array fragment', function () {
+    expect((new PostalAddress(city: 'Berlin'))->toArray())
+        ->not->toHaveKey('@context');
+});
+
+it('renders standalone JSON-LD with @context first', function () {
+    $address = new PostalAddress(
+        street: 'Pariser Platz 1',
+        postal: '10117',
+        city: 'Berlin',
+        country: 'DE',
+    );
+
+    $decoded = json_decode($address->toJsonLd(), true);
+
+    expect($decoded)->toBe([
+        '@context' => 'https://schema.org',
+        '@type' => 'PostalAddress',
+        'streetAddress' => 'Pariser Platz 1',
+        'postalCode' => '10117',
+        'addressLocality' => 'Berlin',
+        'addressCountry' => 'DE',
+    ]);
+});

From 8f050aac2d8c124abb83002878ac9585406ab464 Mon Sep 17 00:00:00 2001
From: Jure Knezovic <jknezovic@byte5.de>
Date: Fri, 19 Jun 2026 13:14:59 +0200
Subject: [PATCH 2/4] feat(address): standardized address creation

Add a typed, swappable way to create an address for a model.

- AddressData: canonical write DTO (fromArray/withType/toArray), plus
  PlaceDetails::toAddressData() and PostalAddress::toAddressData() bridges
- CreatesAddresses contract + default AddressCreator service (bound singleton);
  rebind it to customise creation (dedupe, geocoding, uniqueness, defaults)
- HasAddresses::addAddress(AddressData|array, AddressType|string|null)
- Config::addressesRelation(): single source of truth for the morph wiring
- AddressType roles are now Billing/Shipping/Home/Work (Primary dropped)

The package enforces no cardinality policy (no dedupe/uniqueness/default).
No migration change. Includes the design spec under docs/.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md                              |  68 +++++++++
 src/AddressableServiceProvider.php     |   1 +
 src/App/Concerns/HasAddresses.php      |  30 +++-
 src/App/Contracts/CreatesAddresses.php |  17 +++
 src/App/Data/AddressData.php           |  87 ++++++++++++
 src/App/Data/PlaceDetails.php          |  17 +++
 src/App/Data/PostalAddress.php         |  15 ++
 src/App/Enums/AddressType.php          |   5 +-
 src/App/Services/AddressCreator.php    |  20 +++
 src/App/Support/Config.php             |  12 ++
 tests/Feature/AddressCreationTest.php  | 108 +++++++++++++++
 tests/Unit/AddressDataTest.php         | 182 +++++++++++++++++++++++++
 12 files changed, 554 insertions(+), 8 deletions(-)
 create mode 100644 src/App/Contracts/CreatesAddresses.php
 create mode 100644 src/App/Data/AddressData.php
 create mode 100644 src/App/Services/AddressCreator.php
 create mode 100644 tests/Feature/AddressCreationTest.php
 create mode 100644 tests/Unit/AddressDataTest.php

diff --git a/README.md b/README.md
index a9b4be6..6a94489 100644
--- a/README.md
+++ b/README.md
@@ -172,6 +172,74 @@ $user->latestAddress;
 $address->addressable;
 ```
 
+## Creating addresses
+
+`$model->addAddress($data, $type)` is the standardised entry point for persisting a
+new address. It accepts either an `AddressData` DTO or a loose attribute array, and
+an optional `AddressType` (or its backing string) that overrides whatever type is
+already on the data:
+
+```php
+use Byte5\Addressable\App\Data\AddressData;
+use Byte5\Addressable\App\Enums\AddressType;
+
+// From a typed DTO
+$user->addAddress(new AddressData(
+    street: 'Pariser Platz 1',
+    postal: '10117',
+    city:   'Berlin',
+    country: 'DE',
+), AddressType::Billing);
+
+// From a loose array — internally calls AddressData::fromArray()
+$user->addAddress([
+    'street'  => 'Pariser Platz 1',
+    'postal'  => '10117',
+    'city'    => 'Berlin',
+    'country' => 'DE',
+    'type'    => 'billing',
+]);
+```
+
+Both forms return the persisted `Address` instance.
+
+### `AddressData` — the write DTO
+
+`AddressData` is a readonly DTO that carries the nine address fields (`type`,
+`street`, `extra`, `postal`, `city`, `region`, `latitude`, `longitude`, `country`).
+All fields are optional (default `null`).
+
+The lookup and schema.org DTOs provide typed bridges:
+
+```php
+// From a resolved Google Place
+$details = AddressLookup::details($placeId);   // PlaceDetails
+$data    = $details->toAddressData(AddressType::Shipping);
+
+// From a schema.org PostalAddress DTO
+$postal = $address->toSchemaOrg();             // PostalAddress
+$data   = $postal->toAddressData(AddressType::Billing);
+```
+
+Pass the resulting `AddressData` straight to `addAddress()`.
+
+### Swapping the creation implementation
+
+Address creation is backed by `Byte5\Addressable\App\Contracts\CreatesAddresses`
+(single method: `create(Model $owner, AddressData $data): Address`). The package
+binds the default `AddressCreator` service as a singleton, but you can replace it in
+any service provider:
+
+```php
+use Byte5\Addressable\App\Contracts\CreatesAddresses;
+
+$this->app->bind(CreatesAddresses::class, MyDedupingAddressCreator::class);
+```
+
+The package enforces **no deduplication, per-type uniqueness, or default/primary
+address policy** — that is intentional. Add whatever cardinality rules your
+application needs here.
+
 ## schema.org mapping
 
 The columns map to [schema.org/PostalAddress](https://schema.org/PostalAddress):
diff --git a/src/AddressableServiceProvider.php b/src/AddressableServiceProvider.php
index 4dbedf7..5764699 100644
--- a/src/AddressableServiceProvider.php
+++ b/src/AddressableServiceProvider.php
@@ -36,6 +36,7 @@ public function register(): void
 
         $this->app->singleton(Contracts\AddressRules::class, Services\AddressRules::class);
         $this->app->singleton(Contracts\Countries::class, Services\Countries::class);
+        $this->app->singleton(Contracts\CreatesAddresses::class, Services\AddressCreator::class);
 
         $this->app->singleton(Services\AddressLookupManager::class);
         $this->app->singleton(Services\AddressValidationManager::class);
diff --git a/src/App/Concerns/HasAddresses.php b/src/App/Concerns/HasAddresses.php
index e05e69e..6bc45f2 100644
--- a/src/App/Concerns/HasAddresses.php
+++ b/src/App/Concerns/HasAddresses.php
@@ -2,6 +2,10 @@
 
 namespace Byte5\Addressable\App\Concerns;
 
+use Byte5\Addressable\App\Contracts\CreatesAddresses;
+use Byte5\Addressable\App\Data\AddressData;
+use Byte5\Addressable\App\Enums\AddressType;
+use Byte5\Addressable\App\Models\Address;
 use Byte5\Addressable\App\Support\Config;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\MorphMany;
@@ -17,12 +21,7 @@ trait HasAddresses
      */
     public function addresses(): MorphMany
     {
-        return $this->morphMany(
-            Config::addressModel(),
-            'addressable',
-            'addressable_type',
-            Config::morphKey(),
-        );
+        return Config::addressesRelation($this);
     }
 
     /**
@@ -37,4 +36,23 @@ public function latestAddress(): MorphOne
             Config::morphKey(),
         )->latestOfMany();
     }
+
+    /**
+     * Create and persist a new address for this model.
+     *
+     * Accepts either an AddressData DTO or a loose attribute array. The optional
+     * $type parameter overrides whatever type is already set on the data.
+     */
+    public function addAddress(
+        AddressData|array $data,
+        AddressType|string|null $type = null,
+    ): Address {
+        $data = $data instanceof AddressData ? $data : AddressData::fromArray($data);
+
+        if ($type !== null) {
+            $data = $data->withType($type);
+        }
+
+        return app(CreatesAddresses::class)->create($this, $data);
+    }
 }
diff --git a/src/App/Contracts/CreatesAddresses.php b/src/App/Contracts/CreatesAddresses.php
new file mode 100644
index 0000000..44e293e
--- /dev/null
+++ b/src/App/Contracts/CreatesAddresses.php
@@ -0,0 +1,17 @@
+<?php
+
+namespace Byte5\Addressable\App\Contracts;
+
+use Byte5\Addressable\App\Data\AddressData;
+use Byte5\Addressable\App\Models\Address;
+use Illuminate\Database\Eloquent\Model;
+
+interface CreatesAddresses
+{
+    /**
+     * Persist a new address for the given owner model.
+     *
+     * @param  Model  $owner  A model using the HasAddresses trait.
+     */
+    public function create(Model $owner, AddressData $data): Address;
+}
diff --git a/src/App/Data/AddressData.php b/src/App/Data/AddressData.php
new file mode 100644
index 0000000..737a06d
--- /dev/null
+++ b/src/App/Data/AddressData.php
@@ -0,0 +1,87 @@
+<?php
+
+namespace Byte5\Addressable\App\Data;
+
+use BackedEnum;
+use Byte5\Addressable\App\Enums\AddressType;
+
+readonly class AddressData
+{
+    public function __construct(
+        public AddressType|string|null $type = null,
+        public ?string $street = null,
+        public ?string $extra = null,
+        public ?string $postal = null,
+        public ?string $city = null,
+        public ?string $region = null,
+        public ?float  $latitude = null,
+        public ?float  $longitude = null,
+        public ?string $country = null,
+    ) {}
+
+    /**
+     * Build from a loose attribute array (unknown keys ignored).
+     *
+     * @param array<string, mixed> $attributes
+     */
+    public static function fromArray(array $attributes): self
+    {
+        $type = $attributes['type'] ?? null;
+
+        return new self(
+            type: $type instanceof AddressType ? $type : (is_string($type) ? $type : null),
+            street: isset($attributes['street']) && is_string($attributes['street']) ? $attributes['street'] : null,
+            extra: isset($attributes['extra']) && is_string($attributes['extra']) ? $attributes['extra'] : null,
+            postal: isset($attributes['postal']) && is_string($attributes['postal']) ? $attributes['postal'] : null,
+            city: isset($attributes['city']) && is_string($attributes['city']) ? $attributes['city'] : null,
+            region: isset($attributes['region']) && is_string($attributes['region']) ? $attributes['region'] : null,
+            latitude: isset($attributes['latitude']) && is_numeric($attributes['latitude'])
+                ? (float) $attributes['latitude']
+                : null,
+            longitude: isset($attributes['longitude']) && is_numeric($attributes['longitude'])
+                ? (float) $attributes['longitude']
+                : null,
+            country: isset($attributes['country']) && is_string($attributes['country']) ? $attributes['country'] : null,
+        );
+    }
+
+    /**
+     * Immutable copy with the address type set.
+     */
+    public function withType(AddressType|string $type): self
+    {
+        return new self(
+            type: $type,
+            street: $this->street,
+            extra: $this->extra,
+            postal: $this->postal,
+            city: $this->city,
+            region: $this->region,
+            latitude: $this->latitude,
+            longitude: $this->longitude,
+            country: $this->country,
+        );
+    }
+
+    /**
+     * Column-ready array for `addresses()->create(...)`. `type` is normalised to
+     * its scalar backing value so it works whether or not the model casts `type`
+     * to an enum.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return [
+            'type' => $this->type instanceof BackedEnum ? $this->type->value : $this->type,
+            'street' => $this->street,
+            'extra' => $this->extra,
+            'postal' => $this->postal,
+            'city' => $this->city,
+            'region' => $this->region,
+            'latitude' => $this->latitude,
+            'longitude' => $this->longitude,
+            'country' => $this->country,
+        ];
+    }
+}
diff --git a/src/App/Data/PlaceDetails.php b/src/App/Data/PlaceDetails.php
index f43eff8..6dbb56f 100644
--- a/src/App/Data/PlaceDetails.php
+++ b/src/App/Data/PlaceDetails.php
@@ -2,6 +2,8 @@
 
 namespace Byte5\Addressable\App\Data;
 
+use Byte5\Addressable\App\Enums\AddressType;
+
 readonly class PlaceDetails
 {
     public function __construct(
@@ -33,4 +35,19 @@ public function toArray(): array
             'longitude' => $this->longitude,
         ];
     }
+
+    public function toAddressData(AddressType|string|null $type = null): AddressData
+    {
+        return new AddressData(
+            type: $type,
+            street: $this->street,
+            extra: $this->extra,
+            postal: $this->postal,
+            city: $this->city,
+            region: $this->region,
+            latitude: $this->latitude,
+            longitude: $this->longitude,
+            country: $this->country,
+        );
+    }
 }
diff --git a/src/App/Data/PostalAddress.php b/src/App/Data/PostalAddress.php
index 8172262..8146485 100644
--- a/src/App/Data/PostalAddress.php
+++ b/src/App/Data/PostalAddress.php
@@ -2,6 +2,8 @@
 
 namespace Byte5\Addressable\App\Data;
 
+use Byte5\Addressable\App\Enums\AddressType;
+
 readonly class PostalAddress
 {
     public function __construct(
@@ -43,4 +45,17 @@ public function toJsonLd(): string
             JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE,
         );
     }
+
+    public function toAddressData(AddressType|string|null $type = null): AddressData
+    {
+        return new AddressData(
+            type: $type,
+            street: $this->street,
+            extra: $this->extra,
+            postal: $this->postal,
+            city: $this->city,
+            region: $this->region,
+            country: $this->country,
+        );
+    }
 }
diff --git a/src/App/Enums/AddressType.php b/src/App/Enums/AddressType.php
index 1c994fb..2d2b3f1 100644
--- a/src/App/Enums/AddressType.php
+++ b/src/App/Enums/AddressType.php
@@ -4,7 +4,8 @@
 
 enum AddressType: string
 {
-    case Billing = 'billing';
+    case Billing  = 'billing';
     case Shipping = 'shipping';
-    case Primary = 'primary';
+    case Home     = 'home';
+    case Work     = 'work';
 }
diff --git a/src/App/Services/AddressCreator.php b/src/App/Services/AddressCreator.php
new file mode 100644
index 0000000..c5df37a
--- /dev/null
+++ b/src/App/Services/AddressCreator.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace Byte5\Addressable\App\Services;
+
+use Byte5\Addressable\App\Contracts\CreatesAddresses;
+use Byte5\Addressable\App\Data\AddressData;
+use Byte5\Addressable\App\Models\Address;
+use Byte5\Addressable\App\Support\Config;
+use Illuminate\Database\Eloquent\Model;
+
+final class AddressCreator implements CreatesAddresses
+{
+    public function create(Model $owner, AddressData $data): Address
+    {
+        /** @var Address $address */
+        $address = Config::addressesRelation($owner)->create($data->toArray());
+
+        return $address;
+    }
+}
diff --git a/src/App/Support/Config.php b/src/App/Support/Config.php
index b4aab72..a37e566 100644
--- a/src/App/Support/Config.php
+++ b/src/App/Support/Config.php
@@ -3,6 +3,8 @@
 namespace Byte5\Addressable\App\Support;
 
 use Byte5\Addressable\App\Models\Address;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\MorphMany;
 use Illuminate\Support\Facades\Config as ConfigFacade;
 
 class Config
@@ -16,6 +18,16 @@ public static function addressModel(): string
         return ConfigFacade::string('byte5-addressable.models.address', Address::class);
     }
 
+    /**
+     * The configured polymorphic addresses relation for an owner model.
+     *
+     * @return MorphMany<Address, Model>
+     */
+    public static function addressesRelation(Model $owner): MorphMany
+    {
+        return $owner->morphMany(self::addressModel(), 'addressable', 'addressable_type', self::morphKey());
+    }
+
     public static function addressesTable(): string
     {
         return ConfigFacade::string('byte5-addressable.table_names.addresses', 'addresses');
diff --git a/tests/Feature/AddressCreationTest.php b/tests/Feature/AddressCreationTest.php
new file mode 100644
index 0000000..532e0c0
--- /dev/null
+++ b/tests/Feature/AddressCreationTest.php
@@ -0,0 +1,108 @@
+<?php
+
+use Byte5\Addressable\App\Contracts\CreatesAddresses;
+use Byte5\Addressable\App\Data\AddressData;
+use Byte5\Addressable\App\Enums\AddressType;
+use Byte5\Addressable\App\Models\Address;
+use Byte5\Addressable\Tests\Fixtures\TestModel;
+use Illuminate\Database\Eloquent\Model;
+
+it('addAddress with AddressData persists and returns an Address belonging to the owner', function () {
+    $model = TestModel::create(['name' => 'Acme']);
+
+    $data = new AddressData(
+        type: AddressType::Billing,
+        street: 'Main 10',
+        postal: '10115',
+        city: 'Berlin',
+        country: 'DE',
+    );
+
+    $address = $model->addAddress($data);
+
+    expect($address)->toBeInstanceOf(Address::class)
+        ->and($address->exists)->toBeTrue()
+        ->and($address->street)->toBe('Main 10')
+        ->and($address->city)->toBe('Berlin')
+        ->and($address->postal)->toBe('10115')
+        ->and($address->country)->toBe('DE')
+        ->and($model->addresses()->count())->toBe(1)
+        ->and($model->addresses()->first()->is($address))->toBeTrue();
+});
+
+it('addAddress with a loose array persists via fromArray', function () {
+    $model = TestModel::create(['name' => 'Acme']);
+
+    $address = $model->addAddress([
+        'street' => 'Unter den Linden 1',
+        'city'   => 'Berlin',
+        'postal' => '10117',
+        'country' => 'DE',
+    ]);
+
+    expect($address)->toBeInstanceOf(Address::class)
+        ->and($address->exists)->toBeTrue()
+        ->and($address->street)->toBe('Unter den Linden 1')
+        ->and($address->city)->toBe('Berlin')
+        ->and($address->country)->toBe('DE')
+        ->and($model->addresses()->count())->toBe(1);
+});
+
+it('addAddress with an explicit $type overrides and uppercases country', function () {
+    $model = TestModel::create(['name' => 'Acme']);
+
+    $data = new AddressData(
+        type: AddressType::Shipping,
+        street: 'Marienplatz 1',
+        city: 'Munich',
+        country: 'de',
+    );
+
+    $address = $model->addAddress($data, AddressType::Billing);
+
+    $fresh = $address->fresh();
+
+    expect($fresh)->not->toBeNull()
+        ->and($fresh->country)->toBe('DE')
+        ->and($fresh->type)->toBe(AddressType::Billing);
+});
+
+it('addAddress persists a plain-string type when the enum cast is disabled', function () {
+    config()->set('byte5-addressable.type_enum', '');
+
+    $model = TestModel::create(['name' => 'Acme']);
+
+    $data = new AddressData(type: 'custom', city: 'Berlin');
+
+    $address = $model->addAddress($data);
+
+    expect($address->fresh()->type)->toBe('custom');
+});
+
+it('addAddress routes through the container so the contract can be rebound', function () {
+    $model = TestModel::create(['name' => 'Acme']);
+
+    $sentinel = $model->addresses()->create(['city' => 'Sentinel']);
+    $called   = false;
+
+    app()->bind(CreatesAddresses::class, function () use ($sentinel, &$called): CreatesAddresses {
+        return new class ($sentinel, $called) implements CreatesAddresses {
+            public function __construct(
+                private readonly Address $sentinel,
+                private bool &$called,
+            ) {}
+
+            public function create(Model $owner, AddressData $data): Address
+            {
+                $this->called = true;
+
+                return $this->sentinel;
+            }
+        };
+    });
+
+    $result = $model->addAddress(new AddressData(city: 'Berlin'));
+
+    expect($called)->toBeTrue()
+        ->and($result->is($sentinel))->toBeTrue();
+});
diff --git a/tests/Unit/AddressDataTest.php b/tests/Unit/AddressDataTest.php
new file mode 100644
index 0000000..aec07f5
--- /dev/null
+++ b/tests/Unit/AddressDataTest.php
@@ -0,0 +1,182 @@
+<?php
+
+use Byte5\Addressable\App\Data\AddressData;
+use Byte5\Addressable\App\Data\PlaceDetails;
+use Byte5\Addressable\App\Data\PostalAddress;
+use Byte5\Addressable\App\Enums\AddressType;
+
+it('fromArray() populates all known fields', function () {
+    $data = AddressData::fromArray([
+        'type'      => AddressType::Billing,
+        'street'    => 'Pariser Platz 1',
+        'extra'     => 'Apt. 5',
+        'postal'    => '10117',
+        'city'      => 'Berlin',
+        'region'    => 'Berlin',
+        'latitude'  => 52.5163,
+        'longitude' => 13.3777,
+        'country'   => 'DE',
+    ]);
+
+    expect($data->type)->toBe(AddressType::Billing)
+        ->and($data->street)->toBe('Pariser Platz 1')
+        ->and($data->extra)->toBe('Apt. 5')
+        ->and($data->postal)->toBe('10117')
+        ->and($data->city)->toBe('Berlin')
+        ->and($data->region)->toBe('Berlin')
+        ->and($data->latitude)->toBe(52.5163)
+        ->and($data->longitude)->toBe(13.3777)
+        ->and($data->country)->toBe('DE');
+});
+
+it('fromArray() ignores unknown keys', function () {
+    $data = AddressData::fromArray([
+        'city'    => 'Berlin',
+        'unknown' => 'ignored',
+        'extra_field' => 'also ignored',
+    ]);
+
+    expect($data->city)->toBe('Berlin')
+        ->and($data->street)->toBeNull();
+});
+
+it('toArray() returns all nine column keys', function () {
+    $data = new AddressData(
+        type: AddressType::Shipping,
+        street: 'Unter den Linden 1',
+        extra: null,
+        postal: '10117',
+        city: 'Berlin',
+        region: 'Berlin',
+        latitude: 52.5163,
+        longitude: 13.3777,
+        country: 'DE',
+    );
+
+    expect($data->toArray())->toHaveCount(9)->toHaveKeys([
+        'type', 'street', 'extra', 'postal', 'city', 'region', 'latitude', 'longitude', 'country',
+    ]);
+});
+
+it('toArray() normalises AddressType enum to its backing value', function () {
+    $data = new AddressData(type: AddressType::Billing);
+
+    expect($data->toArray()['type'])->toBe('billing');
+});
+
+it('toArray() passes a plain string type through unchanged', function () {
+    $data = new AddressData(type: 'custom');
+
+    expect($data->toArray()['type'])->toBe('custom');
+});
+
+it('toArray() keeps null type as null', function () {
+    $data = new AddressData();
+
+    expect($data->toArray()['type'])->toBeNull();
+});
+
+it('withType() returns a new instance with the type set and all other fields preserved', function () {
+    $original = new AddressData(
+        type: null,
+        street: 'Pariser Platz 1',
+        extra: 'Apt. 5',
+        postal: '10117',
+        city: 'Berlin',
+        region: 'Berlin',
+        latitude: 52.5163,
+        longitude: 13.3777,
+        country: 'DE',
+    );
+
+    $updated = $original->withType(AddressType::Home);
+
+    expect($updated)->not->toBe($original)
+        ->and($updated->type)->toBe(AddressType::Home)
+        ->and($updated->street)->toBe('Pariser Platz 1')
+        ->and($updated->extra)->toBe('Apt. 5')
+        ->and($updated->postal)->toBe('10117')
+        ->and($updated->city)->toBe('Berlin')
+        ->and($updated->region)->toBe('Berlin')
+        ->and($updated->latitude)->toBe(52.5163)
+        ->and($updated->longitude)->toBe(13.3777)
+        ->and($updated->country)->toBe('DE');
+});
+
+it('withType() leaves the original instance unchanged', function () {
+    $original = new AddressData(type: null, city: 'Berlin');
+    $original->withType(AddressType::Work);
+
+    expect($original->type)->toBeNull();
+});
+
+it('PlaceDetails::toAddressData() maps every field including latitude and longitude', function () {
+    $place = new PlaceDetails(
+        street: 'Pariser Platz 1',
+        extra: 'Apt. 5',
+        postal: '10117',
+        city: 'Berlin',
+        region: 'Berlin',
+        country: 'DE',
+        latitude: 52.5163,
+        longitude: 13.3777,
+    );
+
+    $data = $place->toAddressData();
+
+    expect($data->type)->toBeNull()
+        ->and($data->street)->toBe('Pariser Platz 1')
+        ->and($data->extra)->toBe('Apt. 5')
+        ->and($data->postal)->toBe('10117')
+        ->and($data->city)->toBe('Berlin')
+        ->and($data->region)->toBe('Berlin')
+        ->and($data->latitude)->toBe(52.5163)
+        ->and($data->longitude)->toBe(13.3777)
+        ->and($data->country)->toBe('DE');
+});
+
+it('PlaceDetails::toAddressData() applies the optional type argument', function () {
+    $place = new PlaceDetails(city: 'Berlin');
+
+    $data = $place->toAddressData(AddressType::Work);
+
+    expect($data->type)->toBe(AddressType::Work);
+});
+
+it('PostalAddress::toAddressData() maps location fields and leaves geo null', function () {
+    $postal = new PostalAddress(
+        street: 'Pariser Platz 1',
+        extra: 'Apt. 5',
+        postal: '10117',
+        city: 'Berlin',
+        region: 'Berlin',
+        country: 'DE',
+    );
+
+    $data = $postal->toAddressData();
+
+    expect($data->type)->toBeNull()
+        ->and($data->street)->toBe('Pariser Platz 1')
+        ->and($data->extra)->toBe('Apt. 5')
+        ->and($data->postal)->toBe('10117')
+        ->and($data->city)->toBe('Berlin')
+        ->and($data->region)->toBe('Berlin')
+        ->and($data->latitude)->toBeNull()
+        ->and($data->longitude)->toBeNull()
+        ->and($data->country)->toBe('DE');
+});
+
+it('PostalAddress::toAddressData() applies the optional type argument', function () {
+    $postal = new PostalAddress(city: 'Berlin');
+
+    $data = $postal->toAddressData(AddressType::Billing);
+
+    expect($data->type)->toBe(AddressType::Billing);
+});
+
+it('fromArray() accepts integer coordinates and casts them to float', function () {
+    $data = AddressData::fromArray(['latitude' => 48, 'longitude' => 13]);
+
+    expect($data->latitude)->toBe(48.0)
+        ->and($data->longitude)->toBe(13.0);
+});

From 97caf37b2ea6850b6aefce8b339804b99c4a9d69 Mon Sep 17 00:00:00 2001
From: Jure Knezovic <jknezovic@byte5.de>
Date: Fri, 19 Jun 2026 13:35:02 +0200
Subject: [PATCH 3/4] refactor(address): type creator owner via Addressable
 interface

Replace Config::addressesRelation() (a relation builder living on the config
accessor) with an Addressable contract that the HasAddresses trait satisfies.
CreatesAddresses::create() now takes Model&Addressable $owner and calls
$owner->addresses() directly, so the morphMany wiring lives only in
HasAddresses::addresses(). Models using HasAddresses now declare
`implements Addressable`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md                              |  9 +++++----
 src/App/Concerns/HasAddresses.php      |  9 ++++++++-
 src/App/Contracts/Addressable.php      | 21 +++++++++++++++++++++
 src/App/Contracts/CreatesAddresses.php |  4 +---
 src/App/Services/AddressCreator.php    |  9 +++------
 src/App/Support/Config.php             | 12 ------------
 tests/Feature/AddressCreationTest.php  |  3 ++-
 tests/Fixtures/TestModel.php           |  3 ++-
 8 files changed, 42 insertions(+), 28 deletions(-)
 create mode 100644 src/App/Contracts/Addressable.php

diff --git a/README.md b/README.md
index 6a94489..c0992e5 100644
--- a/README.md
+++ b/README.md
@@ -144,8 +144,9 @@ Add the `HasAddresses` trait to any model that should own addresses:
 
 ```php
 use Byte5\Addressable\App\Concerns\HasAddresses;
+use Byte5\Addressable\App\Contracts\Addressable;
 
-class User extends Model
+class User extends Model implements Addressable
 {
     use HasAddresses;
 }
@@ -226,9 +227,9 @@ Pass the resulting `AddressData` straight to `addAddress()`.
 ### Swapping the creation implementation
 
 Address creation is backed by `Byte5\Addressable\App\Contracts\CreatesAddresses`
-(single method: `create(Model $owner, AddressData $data): Address`). The package
-binds the default `AddressCreator` service as a singleton, but you can replace it in
-any service provider:
+(single method: `create(Model&Addressable $owner, AddressData $data): Address`). The
+package binds the default `AddressCreator` service as a singleton, but you can
+replace it in any service provider:
 
 ```php
 use Byte5\Addressable\App\Contracts\CreatesAddresses;
diff --git a/src/App/Concerns/HasAddresses.php b/src/App/Concerns/HasAddresses.php
index 6bc45f2..bd34823 100644
--- a/src/App/Concerns/HasAddresses.php
+++ b/src/App/Concerns/HasAddresses.php
@@ -2,6 +2,7 @@
 
 namespace Byte5\Addressable\App\Concerns;
 
+use Byte5\Addressable\App\Contracts\Addressable;
 use Byte5\Addressable\App\Contracts\CreatesAddresses;
 use Byte5\Addressable\App\Data\AddressData;
 use Byte5\Addressable\App\Enums\AddressType;
@@ -13,6 +14,7 @@
 
 /**
  * @phpstan-require-extends Model
+ * @phpstan-require-implements Addressable
  */
 trait HasAddresses
 {
@@ -21,7 +23,12 @@ trait HasAddresses
      */
     public function addresses(): MorphMany
     {
-        return Config::addressesRelation($this);
+        return $this->morphMany(
+            Config::addressModel(),
+            'addressable',
+            'addressable_type',
+            Config::morphKey(),
+        );
     }
 
     /**
diff --git a/src/App/Contracts/Addressable.php b/src/App/Contracts/Addressable.php
new file mode 100644
index 0000000..7b59682
--- /dev/null
+++ b/src/App/Contracts/Addressable.php
@@ -0,0 +1,21 @@
+<?php
+
+namespace Byte5\Addressable\App\Contracts;
+
+use Byte5\Addressable\App\Models\Address;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\MorphMany;
+
+/**
+ * A model that owns addresses. Implemented by the HasAddresses trait; declare
+ * `implements Addressable` on any model that uses the trait.
+ */
+interface Addressable
+{
+    /**
+     * All addresses attached to this model.
+     *
+     * @return MorphMany<Address, Model>
+     */
+    public function addresses(): MorphMany;
+}
diff --git a/src/App/Contracts/CreatesAddresses.php b/src/App/Contracts/CreatesAddresses.php
index 44e293e..94d44b6 100644
--- a/src/App/Contracts/CreatesAddresses.php
+++ b/src/App/Contracts/CreatesAddresses.php
@@ -10,8 +10,6 @@ interface CreatesAddresses
 {
     /**
      * Persist a new address for the given owner model.
-     *
-     * @param  Model  $owner  A model using the HasAddresses trait.
      */
-    public function create(Model $owner, AddressData $data): Address;
+    public function create(Model&Addressable $owner, AddressData $data): Address;
 }
diff --git a/src/App/Services/AddressCreator.php b/src/App/Services/AddressCreator.php
index c5df37a..88c478b 100644
--- a/src/App/Services/AddressCreator.php
+++ b/src/App/Services/AddressCreator.php
@@ -2,19 +2,16 @@
 
 namespace Byte5\Addressable\App\Services;
 
+use Byte5\Addressable\App\Contracts\Addressable;
 use Byte5\Addressable\App\Contracts\CreatesAddresses;
 use Byte5\Addressable\App\Data\AddressData;
 use Byte5\Addressable\App\Models\Address;
-use Byte5\Addressable\App\Support\Config;
 use Illuminate\Database\Eloquent\Model;
 
 final class AddressCreator implements CreatesAddresses
 {
-    public function create(Model $owner, AddressData $data): Address
+    public function create(Model&Addressable $owner, AddressData $data): Address
     {
-        /** @var Address $address */
-        $address = Config::addressesRelation($owner)->create($data->toArray());
-
-        return $address;
+        return $owner->addresses()->create($data->toArray());
     }
 }
diff --git a/src/App/Support/Config.php b/src/App/Support/Config.php
index a37e566..b4aab72 100644
--- a/src/App/Support/Config.php
+++ b/src/App/Support/Config.php
@@ -3,8 +3,6 @@
 namespace Byte5\Addressable\App\Support;
 
 use Byte5\Addressable\App\Models\Address;
-use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Relations\MorphMany;
 use Illuminate\Support\Facades\Config as ConfigFacade;
 
 class Config
@@ -18,16 +16,6 @@ public static function addressModel(): string
         return ConfigFacade::string('byte5-addressable.models.address', Address::class);
     }
 
-    /**
-     * The configured polymorphic addresses relation for an owner model.
-     *
-     * @return MorphMany<Address, Model>
-     */
-    public static function addressesRelation(Model $owner): MorphMany
-    {
-        return $owner->morphMany(self::addressModel(), 'addressable', 'addressable_type', self::morphKey());
-    }
-
     public static function addressesTable(): string
     {
         return ConfigFacade::string('byte5-addressable.table_names.addresses', 'addresses');
diff --git a/tests/Feature/AddressCreationTest.php b/tests/Feature/AddressCreationTest.php
index 532e0c0..748f214 100644
--- a/tests/Feature/AddressCreationTest.php
+++ b/tests/Feature/AddressCreationTest.php
@@ -1,5 +1,6 @@
 <?php
 
+use Byte5\Addressable\App\Contracts\Addressable;
 use Byte5\Addressable\App\Contracts\CreatesAddresses;
 use Byte5\Addressable\App\Data\AddressData;
 use Byte5\Addressable\App\Enums\AddressType;
@@ -92,7 +93,7 @@ public function __construct(
                 private bool &$called,
             ) {}
 
-            public function create(Model $owner, AddressData $data): Address
+            public function create(Model&Addressable $owner, AddressData $data): Address
             {
                 $this->called = true;
 
diff --git a/tests/Fixtures/TestModel.php b/tests/Fixtures/TestModel.php
index 885e2f0..3a22cf4 100644
--- a/tests/Fixtures/TestModel.php
+++ b/tests/Fixtures/TestModel.php
@@ -3,9 +3,10 @@
 namespace Byte5\Addressable\Tests\Fixtures;
 
 use Byte5\Addressable\App\Concerns\HasAddresses;
+use Byte5\Addressable\App\Contracts\Addressable;
 use Illuminate\Database\Eloquent\Model;
 
-class TestModel extends Model
+class TestModel extends Model implements Addressable
 {
     use HasAddresses;
 

From e0b6f07d7748583feefca6d31e702a08aef4b72d Mon Sep 17 00:00:00 2001
From: Jure Knezovic <jknezovic@byte5.de>
Date: Fri, 19 Jun 2026 13:38:06 +0200
Subject: [PATCH 4/4] fix(address): correct README enum docs and rebinding test
 spy

Address Copilot review feedback:
- README "Address type enum" still listed the dropped `primary` default;
  update to billing/shipping/home/work.
- Replace the by-reference promoted property in the container-rebinding
  test with a holder-object spy (cleaner, avoids the unusual by-ref pattern).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md                             |  2 +-
 tests/Feature/AddressCreationTest.php | 12 ++++++------
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index c0992e5..1072054 100644
--- a/README.md
+++ b/README.md
@@ -116,7 +116,7 @@ The Address model's **own** primary key is independent of this — it stays a
 ### Address type enum
 
 The `type` column is cast to a string-backed enum. The package ships a default
-`Byte5\Addressable\App\Enums\AddressType` (`billing`, `shipping`, `primary`). You can:
+`Byte5\Addressable\App\Enums\AddressType` (`billing`, `shipping`, `home`, `work`). You can:
 
 - **Replace it** with your own enum to match your application's address roles:
 
diff --git a/tests/Feature/AddressCreationTest.php b/tests/Feature/AddressCreationTest.php
index 748f214..667180c 100644
--- a/tests/Feature/AddressCreationTest.php
+++ b/tests/Feature/AddressCreationTest.php
@@ -84,18 +84,18 @@
     $model = TestModel::create(['name' => 'Acme']);
 
     $sentinel = $model->addresses()->create(['city' => 'Sentinel']);
-    $called   = false;
+    $spy      = (object) ['called' => false];
 
-    app()->bind(CreatesAddresses::class, function () use ($sentinel, &$called): CreatesAddresses {
-        return new class ($sentinel, $called) implements CreatesAddresses {
+    app()->bind(CreatesAddresses::class, function () use ($sentinel, $spy): CreatesAddresses {
+        return new class ($sentinel, $spy) implements CreatesAddresses {
             public function __construct(
                 private readonly Address $sentinel,
-                private bool &$called,
+                private readonly object $spy,
             ) {}
 
             public function create(Model&Addressable $owner, AddressData $data): Address
             {
-                $this->called = true;
+                $this->spy->called = true;
 
                 return $this->sentinel;
             }
@@ -104,6 +104,6 @@ public function create(Model&Addressable $owner, AddressData $data): Address
 
     $result = $model->addAddress(new AddressData(city: 'Berlin'));
 
-    expect($called)->toBeTrue()
+    expect($spy->called)->toBeTrue()
         ->and($result->is($sentinel))->toBeTrue();
 });