tobento/service-country

Country interfaces and resources for PHP applications.

1.0.0 2022-06-15 08:00 UTC

This package is auto-updated.

Last update: 2022-09-15 08:30:15 UTC


README

A country interface for PHP applications.

Table of Contents

Getting started

Add the latest version of the country service project running this command.

composer require tobento/service-country

Requirements

  • PHP 8.0 or greater

Highlights

  • Framework-agnostic, will work with any project
  • Decoupled design

Documentation

Country Repository

The country repository loads the countries from json files.

use Tobento\Service\Country\CountryRepository;
use Tobento\Service\Country\CountryRepositoryInterface;
use Tobento\Service\Country\CountriesFactoryInterface;

$countryRepository = new CountryRepository(
    locale: 'en', // default
    localeFallbacks: ['es' => 'fr'],
    localeMapping: ['en-GB' => 'en'],
    countriesFactory: null, // null|CountriesFactoryInterface
    directory: null, // if null it loads from the provided country files.
);

var_dump($countryRepository instanceof CountryRepositoryInterface);
// bool(true)

Country Repository Interface

use Tobento\Service\Country\CountryRepository;
use Tobento\Service\Country\CountryRepositoryInterface;

$countryRepository = new CountryRepository();

var_dump($countryRepository instanceof CountryRepositoryInterface);
// bool(true)

findCountry

Returns a single country by the specified parameters or null if not found.

use Tobento\Service\Country\CountryRepository;
use Tobento\Service\Country\CountryInterface;

$countryRepository = new CountryRepository();

$country = $countryRepository->findCountry(code: 'US');

var_dump($country instanceof CountryInterface);
// bool(true)

var_dump($country->name());
// string(13) "United States"

// find by specific locale
$country = $countryRepository->findCountry(
    code: 'US',
    locale: 'de'
);

var_dump($country->name());
string(18) "Vereinigte Staaten"

Check out the Country Interface to learn more about the interface.

findCountries

Returns all countries found by the specified parameters.

use Tobento\Service\Country\CountryRepository;
use Tobento\Service\Country\CountriesInterface;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

var_dump($countries instanceof CountriesInterface);
// bool(true)

// find by specific locale and group
$countries = $countryRepository->findCountries(
    locale: 'de',
    group: 'shipping',
);

Check out the Countries Interface to learn more about the interface.

Country

Create Country

use Tobento\Service\Country\Country;
use Tobento\Service\Country\CountryInterface;

$country = new Country(code: 'US');

var_dump($country instanceof CountryInterface);
// bool(true)

Check out the Country Interface to learn more about the interface.

Country Factory

Easily create a country with the provided countryfactory:

createCountry

use Tobento\Service\Country\CountryFactory;
use Tobento\Service\Country\CountryFactoryInterface;
use Tobento\Service\Country\CountryInterface;

$countryFactory = new CountryFactory();

var_dump($countryFactory instanceof CountryFactoryInterface);
// bool(true)

$country = $countryFactory->createCountry(code: 'CH');

var_dump($country instanceof CountryInterface);
// bool(true)

Parameters:

use Tobento\Service\Country\CountryFactory;

$countryFactory = new CountryFactory();

$country = $countryFactory->createCountry(
    code: 'US',
    code3: 'USA',
    numericCode: '840',
    currencyKey: 'USD',
    locale: 'en',
    name: 'United States',
    region: '',
    continent: 'North America',
    id: 840,
    active: true,
    group: 'shipping',
    priority: 100,
);

createCountryFromArray

use Tobento\Service\Country\CountryFactory;

$countryFactory = new CountryFactory();

$country = $countryFactory->createCountryFromArray([
    'code' => 'US',
]);

Country Interface

use Tobento\Service\Country\CountryInterface;
use Tobento\Service\Country\CountryRepository;

$countryRepository = new CountryRepository();
$country = $countryRepository->findCountry('US');

var_dump($country instanceof CountryInterface);
// bool(true)

var_dump($country->code());
// string(2) "US"

var_dump($country->code3());
// string(3) "USA"

var_dump($country->numericCode());
// string(3) "840"

var_dump($country->currencyKey());
// string(3) "USD"

var_dump($country->locale());
// string(2) "en"

var_dump($country->name());
// string(13) "United States"

var_dump($country->region());
// string(0) ""

var_dump($country->continent());
// string(13) "North America"

var_dump($country->timezones());
// array(29) { [0]=> string(12) "America/Adak" ... }

var_dump($country->id());
// int(0)

var_dump($country->active());
// bool(true)

var_dump($country->group());
// string(0) ""

var_dump($country->priority());
// int(0)

with methods

The with methods will return a new instance.

use Tobento\Service\Country\CountryInterface;
use Tobento\Service\Country\CountryRepository;

$countryRepository = new CountryRepository();
$country = $countryRepository->findCountry('US');

var_dump($country instanceof CountryInterface);
// bool(true)

$country = $country->withCurrencyKey('USD');

$country = $country->withLocale('de');

$country = $country->withName('Vereinigte Staaten');

$country = $country->withRegion('Region');

$country = $country->withId(2345);

$country = $country->withActive(false);

$country = $country->withGroup('payment');

$country = $country->withPriority(150);

Countries

Create Countries

use Tobento\Service\Country\Countries;
use Tobento\Service\Country\CountriesInterface;
use Tobento\Service\Country\Country;
use Tobento\Service\Country\CountryInterface;

$countries = new Countries(
    new Country(code: 'US'), // CountryInterface
    new Country(code: 'CH'),
);

var_dump($countries instanceof CountriesInterface);
// bool(true)

Check out Countries Interface to learn more about the interface.

Countries Factory

Easily create a Countries object with the provided countries factory:

createCountries

use Tobento\Service\Country\CountriesFactory;
use Tobento\Service\Country\CountriesFactoryInterface;
use Tobento\Service\Country\CountryFactoryInterface;
use Tobento\Service\Country\CountriesInterface;
use Tobento\Service\Country\CountryInterface;
use Tobento\Service\Country\Country;

$countriesFactory = new CountriesFactory(
    countryFactory: null // null|CountryFactoryInterface
);

var_dump($countriesFactory instanceof CountriesFactoryInterface);
// bool(true)

$countries = $countriesFactory->createCountries(
    new Country(code: 'US'), // CountryInterface
    new Country(code: 'CH'),
);

var_dump($countries instanceof CountriesInterface);
// bool(true)

Check out Countries Interface to learn more about the interface.

createCountriesFromArray

use Tobento\Service\Country\CountriesFactory;
use Tobento\Service\Country\CountriesInterface;

$countriesFactory = new CountriesFactory();

$countries = $countriesFactory->createCountriesFromArray([
    ['code' => 'US'],
    ['code' => 'CH'],
]);

var_dump($countries instanceof CountriesInterface);
// bool(true)

Check out Countries Interface to learn more about the interface.

Countries Interface

use Tobento\Service\Country\CountryRepository;
use Tobento\Service\Country\CountriesInterface;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

var_dump($countries instanceof CountriesInterface);
// bool(true)

addCountry

Adds a country.

use Tobento\Service\Country\CountriesFactory;
use Tobento\Service\Country\CountryInterface;
use Tobento\Service\Country\Country;

$countries = (new CountriesFactory())->createCountries();

$countries->addCountry(
    country: new Country(code: 'US') // CountryInterface
);

addCountries

use Tobento\Service\Country\CountriesFactory;
use Tobento\Service\Country\CountryInterface;
use Tobento\Service\Country\Country;

$countries = (new CountriesFactory())->createCountries();

$countries->addCountries(
    new Country(code: 'US'), // CountryInterface
    new Country(code: 'CH'),
);

sort

Returns a new instance with the countries sorted.

use Tobento\Service\Country\CountryRepository;
use Tobento\Service\Country\CountryInterface;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

// sorted by country name.
$countries = $countries->sort();

// sort by callback.
$countries = $countries->sort(
    fn(CountryInterface $a, CountryInterface $b): int
        => $a->priority() <=> $b->priority()
);

filter

Returns a new instance with the filtered countries.

use Tobento\Service\Country\CountryRepository;
use Tobento\Service\Country\CountryInterface;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$countries = $countries->filter(
    fn(CountryInterface $c): bool => in_array($c->locale(), ['de', 'en'])
);

code

Returns a new instance with the specified code filtered.

use Tobento\Service\Country\CountryRepository;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$countries = $countries->code(code: 'US');

locale

Returns a new instance with the specified locale filtered.

use Tobento\Service\Country\CountryRepository;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$countries = $countries->locale(locale: 'de');

group

Returns a new instance with the specified group filtered.

use Tobento\Service\Country\CountryRepository;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$countries = $countries->group(group: 'shipping');

region

Returns a new instance with the specified region filtered.

use Tobento\Service\Country\CountryRepository;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$countries = $countries->region(region: 'nearBy');

continent

Returns a new instance with the specified continent filtered.

use Tobento\Service\Country\CountryRepository;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$countries = $countries->continent(continent: 'Europe');

all

Returns all countries.

use Tobento\Service\Country\CountryRepository;
use Tobento\Service\Country\CountryInterface;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

foreach($countries->all() as $country) {
    var_dump($country instanceof CountryInterface);
    // bool(true)
}

// or just
foreach($countries as $country) {
    var_dump($country instanceof CountryInterface);
    // bool(true)
}

first

Returns the first country or null if none.

use Tobento\Service\Country\CountryRepository;
use Tobento\Service\Country\CountryInterface;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$country = $countries->first();

var_dump($country instanceof CountryInterface);
// bool(true)

get

Returns the first country found by code, code3, numericCode and/or locale.

use Tobento\Service\Country\CountryRepository;
use Tobento\Service\Country\CountryInterface;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$country = $countries->get(code: 'US');

var_dump($country instanceof CountryInterface);
// bool(true)

// and with locale
$country = $countries->get(code: 'US', locale: 'en');

var_dump($country instanceof CountryInterface);
// bool(true)

column

Returns the column of the countries.

use Tobento\Service\Country\CountryRepository;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$column = $countries->column('name');

var_dump($column);
// array(249) { [0]=> string(11) "Afghanistan" ... }

// indexed by country code 
$column = $countries->column(column: 'name', index: 'code');

var_dump($column);
// { ["AF"]=> string(11) "Afghanistan" ... }

groupedColumn

Returns the column of the countries grouped.

use Tobento\Service\Country\CountryRepository;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$column = $countries->groupedColumn(
    group: 'continent',
    column: 'name',
    index: 'code', // optional
);

print_r($column);
/*Array
(
    [Asia] => Array
        (
            [AF] => Afghanistan
            ...
        )
    [Europe] => Array
        (
            [AX] => Åland Islands
            ...
        )
    ...
)*/

only

Returns a new instance with countries with only the codes specified.

use Tobento\Service\Country\CountryRepository;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$countries = $countries->only(['CH', 'US']);

except

Returns a new instance with countries except the codes specified.

use Tobento\Service\Country\CountryRepository;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$countries = $countries->except(['CH', 'US']);

map

Returns a new instance with the countries mapped.

use Tobento\Service\Country\CountryRepository;
use Tobento\Service\Country\CountryInterface;

$countryRepository = new CountryRepository();

$countries = $countryRepository->findCountries();

$countries = $countries->map(function(CountryInterface $c): CountryInterface {
    if (in_array($c->code(), ['CH', 'FR'])) {
        return $c->withRegion('Near by')->withPriority(100);
    }
    return $c->withRegion('All Others');
});

Credits