Kódy krajín a resolvery

Kódy krajín sa normalizujú už pri vstupe: orežú sa, prevedú na veľké písmená a overí sa, že majú dve alebo tri písmená — tvar kódu ISO 3166-1 alpha-2 alebo alpha-3. Čokoľvek iné vyhodí InvalidCountryException:

use RoundlyConsulting\Addresses\Support\CountryNormaliser;

CountryNormaliser::normalise(' sk ');   // 'SK'
CountryNormaliser::normalise('usa');    // 'USA'
CountryNormaliser::normalise('XX1');    // throws InvalidCountryException

Kontroluje sa len tvar — balík neobsahuje zoznam krajín, takže formálne správny, no nepridelený kód ako XX prejde. Normalizácia beží v AddressData::make(), teda vo všetkých zápisoch cez balík: v builderi, addAddress(), createAddress() aj v UpdateAddressAction s DTO z make().

Ak chcete kódy ukladať presne tak, ako prišli (len orezané, bez kontroly tvaru), normalizáciu vypnite — hodnotou false alebo reťazcom ako 'false', '0' či 'off'. inCountry() ich potom porovnáva bez ohľadu na veľkosť písmen:

// config/addresses.php — store country codes as given (trimmed only, never shape-checked)
'normalise_country' => false,

Názvy krajín

Balík nedodáva zoznam názvov krajín ani geokóder. Ak chcete zisťovať názvy — alebo súradnice — implementujte vo svojej aplikácii kontrakt CountryResolver:

namespace App\Support;

use RoundlyConsulting\Addresses\Contracts\CountryResolver;
use RoundlyConsulting\Addresses\DataTransferObjects\AddressData;
use RoundlyConsulting\Addresses\DataTransferObjects\Coordinates;

final class AppCountryResolver implements CountryResolver
{
    public function name(string $iso): ?string
    {
        return ['SK' => 'Slovakia', 'CZ' => 'Czechia', 'AT' => 'Austria'][$iso] ?? null;
    }

    public function coordinates(AddressData $data): ?Coordinates
    {
        // call your own geocoder here; return null when the address cannot be resolved
        return null;
    }
}

Zaregistrujte ho v konfigurácii. Service provider ho pri registrácii naviaže ako singleton na CountryResolver; pri null alebo prázdnej hodnote nenaviaže nič. Akákoľvek iná hodnota sa overí pri prvom resolvovaní resolvera — musí byť triedou CountryResolver, inak sa vyhodí InvalidConfigurationException s názvom kľúča, takže preklep nikdy nenechá názvy krajín potichu nezistené:

// config/addresses.php
'country_resolver' => \App\Support\AppCountryResolver::class,

S naviazaným resolverom vráti country_name zistený názov, bez neho null. Rovnaká hodnota je aj v AddressResource. Addresses::countryName() zistí názov pre ľubovoľný kód a ak resolver nie je naviazaný alebo kód nepozná, vráti normalizovaný ISO kód:

use RoundlyConsulting\Addresses\Contracts\CountryResolver;
use RoundlyConsulting\Addresses\Facades\Addresses;

$address->country_name;      // 'Slovakia' with a resolver bound, otherwise null
$address->countryName();     // the same value as a method

Addresses::countryName('sk');   // 'Slovakia' — or the normalised 'SK' without a resolver

if (app()->bound(CountryResolver::class)) {
    $name = app(CountryResolver::class)->name('SK');
}

Geokódovanie

Balík coordinates() sám nikdy nevolá — metóda je pre váš kód a vracia value object Coordinates (latitude, longitude) alebo null. Adresu môžete napríklad geokódovať ešte pred uložením:

use RoundlyConsulting\Addresses\Contracts\CountryResolver;
use RoundlyConsulting\Addresses\DataTransferObjects\AddressData;

$data = AddressData::make(
    city: 'Bratislava',
    street: 'Somewhere 1',
    postalCode: '81101',
    countryIso: 'SK',
);

if (app()->bound(CountryResolver::class)) {
    $point = app(CountryResolver::class)->coordinates($data);   // ?Coordinates
    $point?->latitude;
    $point?->longitude;
}

$customer->addAddress($data);

Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

Ďalšie spôsoby podpory vrátane kryptomien

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Podporte našu open-source prácu Pridajte sa k nám na Patreone

Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

Ponuka do 48 hodín Prezrieť všetky balíky