tiny-blocks/country

Value Object representing a country using ISO-3166 specifications.

2.3.1 2025-01-07 01:16 UTC

Requires

• php: ^8.3
• tiny-blocks/value-object: ^3

Requires (Dev)

• infection/infection: ^0
• phpmd/phpmd: ^2.15
• phpstan/phpstan: ^1
• phpunit/phpunit: ^11
• squizlabs/php_codesniffer: ^3

MIT

• Gustavo Freze de Araujo Santos

• country
• psr
• value-object
• vo
• tiny-blocks

README

• Overview
• Installation
• How to use
• License
• Contributing

Overview

Value Object representing a country using ISO-3166 specifications.

Installation

composer require tiny-blocks/country

How to use

The library exposes country codes according to ISO-3166 specifications. Also, it is possible to create a representation of a country that groups the codes and its name.

Alpha2Code

A two-letter code that represents a country name, recommended as the general purpose code.

$alpha2Code = Alpha2Code::UNITED_STATES_OF_AMERICA;

$alpha2Code->name;              # UNITED_STATES_OF_AMERICA
$alpha2Code->value;             # US
$alpha2Code->toAlpha3()->value; # USA

Alpha3Code

A three-letter code that represents a country name, which is usually more closely related to the country name.

$alpha3Code = Alpha3Code::UNITED_STATES_OF_AMERICA;

$alpha3Code->name;              # UNITED_STATES_OF_AMERICA
$alpha3Code->value;             # USA
$alpha3Code->toAlpha2()->value; # US

Country

A Country instance can be created using either an Alpha-2 or Alpha-3 code, along with an optional country name. There are two main methods to create a Country object: from (which accepts objects) and fromString (which accepts strings).

Creating from objects

You can create a Country instance using the from method by providing an Alpha2Code or Alpha3Code object. Optionally, you can pass the name of the country. If no name is provided, the default is the English version of the country name.

$country = Country::from(alphaCode: Alpha2Code::UNITED_STATES_OF_AMERICA);

$country->name;          # United States of America
$country->alpha2->value; # US
$country->alpha3->value; # USA

or

$country = Country::from(alphaCode: Alpha3Code::UNITED_STATES_OF_AMERICA);

$country->name;          # United States of America
$country->alpha2->value; # US
$country->alpha3->value; # USA

If you want to specify a custom name:

$country = Country::from(alphaCode: Alpha3Code::UNITED_STATES_OF_AMERICA, name: 'United States');

$country->name;          # United States
$country->alpha2->value; # US
$country->alpha3->value; # USA

Creating from string

Alternatively, you can create a Country instance using the fromString method, which accepts an Alpha-2 or Alpha-3 code as a string. This method is useful when the alpha code is provided as a string.

$country = Country::fromString(alphaCode: 'US');

$country->name;          # United States of America
$country->alpha2->value; # US
$country->alpha3->value; # USA

You can also pass a custom country name when using the fromString method:

$country = Country::fromString(alphaCode: 'USA', name: 'United States');

$country->name;          # United States
$country->alpha2->value; # US
$country->alpha3->value; # USA

License

Country is licensed under MIT.

Contributing

Please follow the contributing guidelines to contribute to the project.