PHPackages                             tobento/service-country - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. tobento/service-country

ActiveLibrary[Utility & Helpers](/categories/utility)

tobento/service-country
=======================

Country interfaces and resources for PHP applications.

2.0(7mo ago)0911MITPHPPHP >=8.4

Since Jun 15Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/tobento-ch/service-country)[ Packagist](https://packagist.org/packages/tobento/service-country)[ Docs](https://www.tobento.ch)[ RSS](/packages/tobento-service-country/feed)WikiDiscussions 2.x Synced 1mo ago

READMEChangelog (2)Dependencies (4)Versions (4)Used By (1)

Country Service
===============

[](#country-service)

A country interface for PHP applications.

Table of Contents
-----------------

[](#table-of-contents)

- [Getting started](#getting-started)
    - [Requirements](#requirements)
    - [Highlights](#highlights)
- [Documentation](#documentation)
    - [Country Repository](#country-repository)
    - [Country Repository Interface](#country-repository-interface)
    - [Country](#country)
        - [Create Country](#create-country)
        - [Country Factory](#country-factory)
        - [Country Interface](#country-interface)
    - [Countries](#countries)
        - [Create Countries](#create-countries)
        - [Countries Factory](#countries-factory)
        - [Countries Interface](#countries-interface)
- [Credits](#credits)

---

Getting started
===============

[](#getting-started)

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

```
composer require tobento/service-country

```

Requirements
------------

[](#requirements)

- PHP 8.4 or greater

Highlights
----------

[](#highlights)

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

Documentation
=============

[](#documentation)

Country Repository
------------------

[](#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
----------------------------

[](#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](#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](#countries-interface) to learn more about the interface.

Country
-------

[](#country)

### Create 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](#country-interface) to learn more about the interface.

### Country Factory

[](#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

[](#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
---------

[](#countries)

### Create 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](#countries-interface) to learn more about the interface.

### Countries Factory

[](#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](#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](#countries-interface) to learn more about the interface.

### Countries 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
=======

[](#credits)

- [Tobias Strub](https://www.tobento.ch)
- [All Contributors](../../contributors)

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance62

Regular maintenance activity

Popularity12

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~399 days

Total

4

Last Release

231d ago

Major Versions

1.x-dev → 2.02025-09-23

PHP version history (2 changes)1.0.0PHP >=8.0

2.0PHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/055d6a1b5c2384bb179c75ab0b55914231d898fdc4dffeb30770f81200e52206?d=identicon)[TOBENTOch](/maintainers/TOBENTOch)

---

Top Contributors

[![tobento-ch](https://avatars.githubusercontent.com/u/16684832?v=4)](https://github.com/tobento-ch "tobento-ch (5 commits)")

---

Tags

phppackagecountriescountrytobento

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tobento-service-country/health.svg)

```
[![Health](https://phpackages.com/badges/tobento-service-country/health.svg)](https://phpackages.com/packages/tobento-service-country)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)