hawara/spanish-locales

Countries, language names and currencies and their translations to Spanish, Galician, Euskera and Catalan

1.0.0 2024-05-24 16:36 UTC

Requires (Dev)

• pestphp/pest: ^2.34
• psy/psysh: ^0.12.3

MIT

• Carlos Capote Pérez-Andreu

README

This library provides information about countries, languages and currencies in Catalan, Spanish, Euskera and Galician.

JSON Database

Two folders contain the base information in readable JSON format:

• data/ contains the base files with one record per entity:
  • countries.json
  • currencies.json
  • languages.json
• translations/ contains the corresponding translations:
  • ca/ for Catalan
  • es/ for Spanish
  • eu/ for Euskera
  • ga/ for Galician

Programming Interface

As the library was created in order to be part of the Cowork web application, it offers a programming interface that can easily be consumed from any PHP application.

Installation

In order to use the data via PHP, first use composer to install the package:

composer require hawara/spanish-locales

Usage

Then, just use the corresponding class to access the information you want.

Use

All the classes in the library are in the Hawara\SpanishLocales namespace.

use Hawara\SpanishLocales\Countries;
use Hawara\SpanishLocales\Currencies;
use Hawara\SpanishLocales\Languages;

Instantiate

You can either instantiate those classes without any argument:

$countries = new Countries;
$currencies = new Currencies;
$languages = new Languages;

... by passing it the path to an alternative JSON file:

$countries = new Countries(__DIR__.'/data/countries.json');
$currencies = new Currencies(__DIR__.'/data/currencies.json');
$languages = new Languages(__DIR__.'/data/languages.json');

... and/or by passing it the list of languages that you wish to include:

$countries = new Countries(languages: ['ca', 'es', 'eu', 'gl']);
$currencies = new Currencies(languages: ['ca', 'es', 'eu', 'gl']);
$languages = new Languages(languages: ['ca', 'es', 'eu', 'gl']);

Countries

Iterate

The iterate method offers you access to these properties for each country:

Property	Example
alpha_2	ES
alpha_3	ESP
numeric_code	724
flag	🇪🇸

foreach($countries->iterate() as $country) {
    print_r([
        'alpha_2' => $country->alpha_2,
        'alpha_3' => $country->alpha_3,
        'numeric_code' => $country->numeric_code,
        'flag' => $country->flag,
    ]);
}

If you specified some languages when you instantiated the countries object, you'll obtain them as an extra translations property:

{
  "alpha_2": "AX",
  "alpha_3": "ALA",
  "numeric_code": "248",
  "flag": "🇦🇽",
  "translations": {
    "ca": "Illes Åland",
    "es": "Islas Åland",
    "eu": "Åland uharteak",
    "gl": "Illas Åland"
  }
}

Locate countries.json

The getPath method returns the path to the base JSON file that contains the countries.

$countries->getPath();

//your/path/to/data/countries.json

Currencies

Iterate

The iterate method offers you access to these properties for each currency:

Property	Example
letter_code	EUR
numeric_code	978

foreach($currencies->iterate() as $currency) {
    print_r([
        'letter_code' => $currency->letter_code,
        'numeric_code' => $currency->numeric_code,
    ]);
}

Locate currencies.json

The getPath method returns the path to the base JSON file that contains the currencies.

$currencies->getPath();

//your/path/to/data/currencies.json

Languages

Iterate

The iterate method offers you access to these properties for each language:

Property	Example
alpha_2	es
alpha_3	spa

foreach($languages->iterate() as $language) {
    print_r([
        'alpha_2' => $language->alpha_2,
        'alpha_3' => $language->alpha_3,
    ]);
}

Locate languages.json

The getPath method returns the path to the base JSON file that contains the languages.

$languages->getPath();

//your/path/to/data/languages.json

Development

Automated Tests

To run the tests, you need to have the package installed with its corresponding development dependencies. If you have them already installed, just use Pest to run the tests:

./vendor/bin/pest

Interactive Tests

In order to facilitate the execution of manual or interactive tests, Psysh is also available. Just run:

./vendor/bin/psysh

... and you'll be able to consume the Hawara\SpanishLocales namespace:

iterator_to_array(
    (new Hawara\SpanishLocales\Languages)->iterate()
);