AddressData & CreateAddressAction

Injecting the manager and the full facade → action map live in DI and actions. For imports, seeders and services, build an AddressData and hand it to the address book — or to the trait’s addAddress():

use RoundlyConsulting\Addresses\DataTransferObjects\AddressData;
use RoundlyConsulting\Addresses\Enums\AddressType;

$payer->addAddress(AddressData::make(
    city: 'Bratislava',
    street: 'Somewhere 1',
    postalCode: '81101',
    countryIso: 'SK',
    type: AddressType::Office,
    isPrimary: true,
));

AddressData

AddressData is a final readonly value object. Use the make() factory with named arguments:

Property	Type	Default
`city`	string	—
`street`	string	—
`postalCode`	string	—
`countryIso`	string	—
`name`	?string	null
`type`	?AddressType	null → config default_type
`isPrimary`	bool	false
`meta`	?Collection	null

use Illuminate\Support\Collection;
use RoundlyConsulting\Addresses\DataTransferObjects\AddressData;
use RoundlyConsulting\Addresses\Enums\AddressType;

$data = AddressData::make(
    city: '  Bratislava ',        // trimmed to 'Bratislava'
    street: 'Somewhere 1',
    postalCode: '81101',
    countryIso: ' sk ',           // normalised to 'SK'
    name: 'HQ',
    type: AddressType::Billing,
    isPrimary: true,
    meta: Collection::make(['floor' => 3]),
);

$data->toAttributes();
// ['type' => 'billing', 'is_primary' => true, 'name' => 'HQ', 'city' => 'Bratislava',
//  'street' => 'Somewhere 1', 'postal_code' => '81101', 'country_iso' => 'SK', 'meta' => Collection]

make() trims city, street, postal code and name (a blank name becomes null) and normalises the country when normalise_country is on. Constructing new AddressData(...) directly skips both — use make() unless the values are already clean. Leave type out of either and it resolves to the configured default_type. meta takes a Collection or null; the builder’s meta() accepts any iterable and wraps it for you.

createAddress()

The trait’s named-argument shortcut builds an AddressData via make() and delegates to addAddress(); leave type out and the address gets default_type. Note that the argument is countryIsoCode here, not countryIso:

use Illuminate\Support\Collection;
use RoundlyConsulting\Addresses\Enums\AddressType;

$address = $customer->createAddress(
    city: 'Bratislava',
    street: 'Somewhere 1',
    postalCode: '81101',
    countryIsoCode: 'sk',          // normalised to 'SK'
    name: 'HQ',
    isPrimary: true,
    type: AddressType::Billing,
    meta: Collection::make(['floor' => 3]),
);

CreateAddressAction

The address book, the builder and the trait all delegate to CreateAddressAction. Resolve it from the container to create an address on any Eloquent model, with or without the trait — it inserts the row and, for isPrimary: true, promotes it in the same transaction, then dispatches AddressCreated (and PrimaryAddressChanged for a promotion):

use RoundlyConsulting\Addresses\Actions\CreateAddressAction;
use RoundlyConsulting\Addresses\DataTransferObjects\AddressData;

// works on any Eloquent model — the HasAddresses trait is not required
$address = app(CreateAddressAction::class)->execute(
    $warehouse,
    AddressData::make(
        city: 'Bratislava',
        street: 'Somewhere 1',
        postalCode: '81101',
        countryIso: 'SK',
        isPrimary: true,
    ),
);

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages