World Countries

https://github.com/mledoze/countries
Admin
World Countries is a comprehensive dataset containing information about all world countries in JSON,...
Tokens:41,096
Snippets:330
Trust Score:8.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Change output directory usage example

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/countries-php-cli.md

Shows how to change the output directory using the --output-dir option. The example first creates the directory with mkdir.

```sh
mkdir foobar
php countries.php convert --output-dir=foobar
```

--------------------------------

### Install dependencies with Composer

Source: https://github.com/mledoze/countries/blob/master/README.md

Run this command in the project root to install required PHP dependencies before using the conversion script.

```sh
composer install
```

--------------------------------

### ExportCommand instantiation in countries.php

Source: https://github.com/mledoze/countries/blob/master/_autodocs/configuration.md

Wiring example that creates an ExportCommand with the countries.json input and dist output directory, both relative to the script's directory.

```php
$application->add(new ExportCommand(
	__DIR__ . DIRECTORY_SEPARATOR . 'countries.json',
	__DIR__ . DIRECTORY_SEPARATOR . 'dist'
));
```

--------------------------------

### Select output formats usage examples

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/countries-php-cli.md

Shows how to select output formats using the --format option in both long and short forms. The option can be repeated to specify multiple formats.

```sh
php countries.php convert --format=json_unescaped --format=csv
php countries.php convert -f json_unescaped -f csv
```

--------------------------------

### Generate dist files with composer and php

Source: https://github.com/mledoze/countries/blob/master/CONTRIBUTING.md

Commands to install dependencies and regenerate the distribution files in the dist folder using the countries.php script.

```bash
composer install
php countries.php convert
```

--------------------------------

### Basic usage of JsonConverterUnicode

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/json-converter-unicode.md

Example showing how to instantiate the converter and save the resulting unescaped JSON to a file.

```php
use MLD\Converter\JsonConverterUnicode;

$converter = new JsonConverterUnicode();

$json = $converter->convert($countries);
file_put_contents('dist/countries-unescaped.json', $json);
```

--------------------------------

### Resulting document shape (first record, abridged)

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/yaml-converter.md

Example YAML output showing the structure of the first record, with inline collections and unquoted keys where possible.

```yaml
- { name: { common: Aruba, official: Aruba, native: { nld: { official: Aruba, common: Aruba }, pap: { official: Aruba, common: Aruba } } }, tld: [.aw], cca2: AW, ccn3: '533', cca3: ABW, cioc: ARU, independent: false, status: officially-assigned, unMember: false, currencies: { AWG: { name: 'Aruban florin', symbol: ƒ } }, idd: { root: '+2', suffixes: ['97'] }, capital: [Oranjestad], altSpellings: [AW], region: Americas, subregion: Caribbean, languages: { nld: Dutch, pap: Papiamento }, translations: { ces: { official: Aruba, common: Aruba }, ... }, latlng: [12.5, -69.96666666], landlocked: false, borders: {  }, area: 180, flag: 🇦🇼, demonyms: { eng: { f: Aruban, m: Aruban }, fra: { f: Arubaise, m: Arubais } }, callingCodes: ['+297'] }
```

--------------------------------

### flatten() behavioral example with default separator

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/abstract-converter.md

Shows a sample country array and the conceptual output of flatten() with default settings. Demonstrates how nested keys become dot-joined paths, numeric arrays are comma-joined, empty arrays become empty strings, and true becomes "1".

```php
// input
$country = [
    'name' => ['common' => 'Austria', 'official' => 'Republic of Austria'],
    'tld'  => ['.at'],
    'landlocked' => true,
    'borders' => [],
    'latlng' => [47.33333333, 13.33333333],
];

// flatten($country) yields (conceptually)
// 'name.common'   => 'Austria'
// 'name.official' => 'Republic of Austria'
// 'tld'           => '.at'
// 'landlocked'    => '1'
// 'borders'       => ''
// 'latlng'        => '47.33333333,13.33333333'
```

--------------------------------

### CsvConverter::convert()

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/csv-converter.md

Documentation for the CsvConverter::convert() method, including parameters, return type, formatting rules, usage examples, and error handling.

```APIDOC
## `CsvConverter::convert()`

### Description
Converts an array of country data into a CSV document. The output includes a header line with dot-path column names and one line per country, with cells joined by `","` and each line separated by `PHP_EOL`.

### Method
`public function convert(array $countries): string`

### Parameters
- **$countries** (array) - Required - Countries data array (associative maps).

### Return Type
`string` - A CSV document: one header line (quoted dot-path column names separated by `","`), then one quoted, `","`-joined line per country, all lines separated by `PHP_EOL`. The document ends with a trailing newline.

### Formatting Rules
- Nested maps become dot-path columns: `name.common`, `idd.root`, `translations.deu.official`.
- Arrays become comma-joined strings: `tld` → `.at`, `borders` → `CZE,DEU,...`.
- Empty arrays become the empty string.
- Boolean `false` becomes `"0"`; `true` becomes `"1"`.
- Pre-processing: `extractCurrencyCodes()` keeps only currency codes (e.g., `EUR`); `extractLanguages()` keeps only language names (e.g., `Dutch,Papiamento`); `removeNativeNames()` removes `name.native` entirely.

### Header Derivation
`buildHeadersLine()` applies the same transformations to the first country (`$countries[0]`), flattens it, and uses the flattened keys as the header row.

### Throws
None declared. Input is assumed to be well-formed country maps.

### Usage Example
```php
use MLD\Converter\CsvConverter;

$converter = new CsvConverter();
$csv = $converter->convert($countries);
file_put_contents('dist/countries.csv', $csv);
```

### Resulting Document Shape (First Row)
```csv
"name.common","name.official","tld","cca2","ccn3","cca3","cioc","independent","status","unMember","currencies","idd.root","idd.suffixes","capital","altSpellings","region","subregion","languages","translations.ara.official","translations.ara.common",...
"Aruba","Aruba",".aw","AW","533","ABW","ARU","0","officially-assigned","0","AWG","+2","97","Oranjestad","AW","Americas","Caribbean","Dutch,Papiamento","أروبا","أروبا",...
```

### Error Handling
`convert()` indexes `$countries[0]` for the header; passing an empty array would dereference an absent first element. Guard non-empty input when calling directly.

```php
use MLD\Converter\CsvConverter;

$converter = new CsvConverter();
if (!empty($countries)) {
    $csv = $converter->convert($countries);
} else {
    printf('Nothing to convert\n');
}
```
```

--------------------------------

### JSON country data example for Austria

Source: https://github.com/mledoze/countries/blob/master/README.md

Example JSON object for Austria from the countries dataset. Shows the structure of country data including names, codes, currencies, translations, borders, and flag emoji. Note the missing comma after "callingCodes" array in the original example.

```json
{
	"name": {
		"common": "Austria",
		"official": "Republic of Austria",
		"native": {
			"bar": {
				"official": "Republik Österreich",
				"common": "Österreich"
			}
		}
	},
	"tld": [".at"],
	"cca2": "AT",
	"ccn3": "040",
	"cca3": "AUT",
	"cioc": "AUT",
	"independent": true,
	"status": "officially-assigned",
	"unMember": true,
	"unRegionalGroup": "Western European and Others Group",
	"currencies": {"EUR": {"name": "Euro", "symbol": "\u20ac"}},
	"idd": {
		"root": "+4",
		"suffixes": ["3"]
	},
	"capital": ["Vienna"],
	"altSpellings": ["AT", "Osterreich", "Oesterreich"],
	"region": "Europe",
	"subregion": "Western Europe",
	"languages": {
		"bar": "Austro-Bavarian German"
	},
	"translations": {
		"cym": {"official": "Republic of Austria", "common": "Awstria"},
		"deu": {"official": "Republik Österreich", "common": "Österreich"},
		"fra": {"official": "République d'Autriche", "common": "Autriche"},
		"hrv": {"official": "Republika Austrija", "common": "Austrija"},
		"ita": {"official": "Repubblica d'Austria", "common": "Austria"},
		"jpn": {"official": "オーストリア共和国", "common": "オーストリア"},
		"nld": {"official": "Republiek Oostenrijk", "common": "Oostenrijk"},
		"por": {"official": "República da Áustria", "common": "Áustria"},
		"rus": {"official": "Австрийская Республика", "common": "Австрия"},
		"spa": {"official": "República de Austria", "common": "Austria"}
	},
	"latlng": [47.33333333, 13.33333333],
	"demonyms": {
		"fra": {
			"f": "Autrichienne",
			"m": "Autrichien"
		},
		"spa": {
			"f": "Austriaco",
			"m": "Austriaca"
		}
	},
	"landlocked": true,
	"borders": ["CZE", "DEU", "HUN", "ITA", "LIE", "SVK", "SVN", "CHE"],
	"area": 83871,
	"callingCodes": ["+43"]
	"flag": "\ud83c\udde6\ud83c\uddf9"
}
```

--------------------------------

### Include only some fields usage examples

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/countries-php-cli.md

Shows how to include only specific fields using the --include-field option in both long and short forms. The option can be repeated to include multiple fields.

```sh
php countries.php convert --include-field=name --include-field=area
php countries.php convert -i name -i area
```

--------------------------------

### Invocation command: php countries.php convert

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/countries-php-cli.md

Runs the convert command from the repository root after composer install. This is the primary way to invoke the CLI.

```sh
php countries.php convert
```

--------------------------------

### Before adding a language to countries.json

Source: https://github.com/mledoze/countries/blob/master/CONTRIBUTING.md

Shows the original JSON structure for a country entry before adding a new language translation. The example includes the native name object and languages map with Spanish as the only language.

```JSON
{
    "name": {
        "common": "Argentina",
        "official": "Argentine Republic",
        "native": {
            "spa": {
                "official": "Rep\u00fablica Argentina",
                "common": "Argentina"
            }
        }
    },
    "...": "...",
    "languages": {
        "spa": "Spanish"
    }
},
```

--------------------------------

### Resulting document shape (first row)

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/csv-converter.md

Example of the CSV output's first row, showing the header and first data line with quoted, comma-separated values.

```csv
"name.common","name.official","tld","cca2","ccn3","cca3","cioc","independent","status","unMember","currencies","idd.root","idd.suffixes","capital","altSpellings","region","subregion","languages","translations.ara.official","translations.ara.common",...
"Aruba","Aruba",".aw","AW","533","ABW","ARU","0","officially-assigned","0","AWG","+2","97","Oranjestad","AW","Americas","Caribbean","Dutch,Papiamento","أروبا","أروبا",...
```

--------------------------------

### Basic: enumerate values of the consuming enum

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/enum-values.md

Shows how to use Formats::values() to get the list of output format ids and iterate over them. The output is ['csv', 'json', 'json_unescaped', 'xml', 'yml'].

```php
use MLD\Enum\Formats;

$formats = Formats::values();
// ['csv', 'json', 'json_unescaped', 'xml', 'yml']

foreach ($formats as $format) {
    printf('-%s ', $format);
}
```

--------------------------------

### Exclude fields usage examples

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/countries-php-cli.md

Shows how to exclude fields using the --exclude-field option in both long and short forms. The option can be repeated to exclude multiple fields.

```sh
php countries.php convert --exclude-field=tld
php countries.php convert --exclude-field=tld --exclude-field=cca2
php countries.php convert -x tld -x cca2
```

--------------------------------

### Basic usage with ES modules

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/js-entry-point.md

Shows how to import the countries array using ES module syntax and access nested properties like `currencies.EUR.symbol` and `latlng`. The example finds Germany by `cca3` code.

```javascript
import countries from 'world-countries';

const de = countries.find(c => c.cca3 === 'DEU');
console.log(de.currencies.EUR.symbol);    // "€" (as parsed from \u20ac)
console.log(de.latlng);                   // [51, 9]
```

--------------------------------

### Usage with TypeScript types

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/js-entry-point.md

Shows how to use the package with TypeScript, importing the `Country` type and leveraging type checking on the `countries` array. The example finds Austria and iterates over all countries to access `latlng` as a number.

```typescript
import countries, { Country } from 'world-countries';

const austrian: Country | undefined = countries.find(c => c.cca2 === 'AT');

// countries is typed Country[], so members are checked at compile time
for (const c of countries) {
  const latitude: number = c.latlng[0]; // OK
}
```

--------------------------------

### Concrete output shape example

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/abstract-json-converter.md

Shows the concrete output shape of the convert() method. Each country object is placed on its own line, with whitespace and indentation depending on the encoder of the concrete subclass and formatOutput-style settings. The base class only guarantees the newline between '}' and '{'.

```json
[
{
  "name": {"common": "Aruba", ...}
},
{
  "name": {"common": "Afghanistan", ...}
}
]
```

--------------------------------

### Basic usage with require in Node.js

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/js-entry-point.md

Shows how to load the countries array using CommonJS `require` and access properties like `length`, `name.common`, `area`, and `flag`. The example finds Austria by `cca2` code.

```javascript
const countries = require('world-countries');

console.log(countries.length);            // 250
const austria = countries.find(c => c.cca2 === 'AT');
console.log(austria.name.common);         // "Austria"
console.log(austria.area);                // 83871
console.log(austria.flag);                // "🇦🇹"
```

--------------------------------

### Catch InvalidArgumentException from Factory::create()

Source: https://github.com/mledoze/countries/blob/master/_autodocs/errors.md

Catches the InvalidArgumentException thrown by Factory::create() when an unsupported format is requested. The example uses 'toml' as the format, which is not in Formats::values(), and prints the exception message.

```php
use MLD\Converter\Factory;
use InvalidArgumentException;

$factory = new Factory();
try {
    $converter = $factory->create('toml');
} catch (InvalidArgumentException $exception) {
    printf('Unsupported format %s\n', $exception->getMessage());
}
```

--------------------------------

### JsonConverterUnicode::convert() with error handling

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/abstract-json-converter.md

Converts an array of country data to a JSON string, throwing a JsonException on encoding failure. This example demonstrates proper error handling when conversion fails.

```APIDOC
## JsonConverterUnicode::convert()

### Description
Converts an array of country data to a JSON string, throwing a JsonException on encoding failure. This example demonstrates proper error handling when conversion fails.

### Method
convert

### Parameters
- **$countries** (array) - Required - The array of country data to convert.

### Exceptions
- **JsonException** - Thrown if the JSON encoding fails.

### Example
php
use MLD\Converter\JsonConverterUnicode;
use JsonException;

$converter = new JsonConverterUnicode();
try {
    $json = $converter->convert($countries);
} catch (JsonException $exception) {
    printf('Countries data could not be JSON-encoded: %s\n', $exception->getMessage());
}

```

--------------------------------

### Extend AbstractConverter to create a custom KeyValueConverter

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/abstract-converter.md

Shows how to extend AbstractConverter and implement the required convert() method. The protected flatten() helper is available for flattening each country array. This example iterates over countries, flattens each, and builds lines with index and key=value pairs, joined by PHP_EOL.

```php
use MLD\Converter\AbstractConverter;

class KeyValueConverter extends AbstractConverter
{
    public function convert(array $countries): string
    {
        $lines = [];
        foreach ($countries as $index => $country) {
            $flat = $this->flatten($country);
            $lines[] = sprintf('[%d]', $index);
            foreach ($flat as $key => $value) {
                $lines[] = sprintf('%s=%s', $key, $value);
            }
        }
        return implode(PHP_EOL, $lines);
    }
}
```

--------------------------------

### Catch LogicException from ExportCommand constructor

Source: https://github.com/mledoze/countries/blob/master/_autodocs/errors.md

Catch LogicException thrown by ExportCommand constructor when registering a command with a colliding or invalid name. The message is framework-defined and not printed by the project. The example shows adding the command to the application.

```php
use MLD\Console\Command\ExportCommand;
use Symfony\Component\Console\Exception\LogicException;

try {
    $command = new ExportCommand('countries.json', 'dist', 'convert');
    $application->add($command);
} catch (LogicException $exception) {
    // e.g. duplicate command registration
    printf('Command registration failed: %s\n', $exception->getMessage());
}
```

--------------------------------

### configure() method definition

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/export-command.md

Defines the command's options: --exclude-field (-x), --include-field (-i), --format (-f), and --output-dir. The exclude and include options are mutually exclusive. Defaults are set for include-field (all fields), format (all formats), and output-dir (the configured output directory).

```php
protected function configure(): void
{
    $this
        ->setDescription('Converts source country data to various output formats')
        ->addOption(
            ExportCommandOptions::EXCLUDE_FIELD->value,
            'x',
            InputOption::VALUE_IS_ARRAY | InputOption::VALUE_REQUIRED,
            'If set, excludes top-level field with the given name from the output. Cannot be used with --include-field',
            []
        )
        ->addOption(
            ExportCommandOptions::INCLUDE_FIELD->value,
            'i',
            InputOption::VALUE_IS_ARRAY | InputOption::VALUE_REQUIRED,
            'If set, include only these top-level fields with the given name from the output. Cannot be used with --exclude-field',
            Fields::values()
        )
        ->addOption(
            ExportCommandOptions::FORMAT->value,
            'f',
            InputOption::VALUE_IS_ARRAY | InputOption::VALUE_REQUIRED,
            'Output formats',
            Formats::values()
        )
        ->addOption(
            ExportCommandOptions::OUTPUT_DIR->value,
            null,
            InputOption::VALUE_OPTIONAL | InputOption::VALUE_REQUIRED,
            'Directory where you want to put output files',
            $this->outputDirectory
        );
}
```

--------------------------------

### XmlConverter initializeDomDocument() method

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/xml-converter.md

Sets up the DOMDocument with UTF-8 encoding, formatted output, and a root <countries> element. Throws DOMException on failure.

```php
$this->domDocument = new DOMDocument('1.0', 'UTF-8');
$this->domDocument->formatOutput = true;
$this->domDocument->preserveWhiteSpace = false;
$this->domDocument->appendChild($this->domDocument->createElement('countries'));
```

--------------------------------

### Equivalent dispatch table as used by the CLI

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/converter-factory.md

Shows a loop over format strings, creating converters and converting data, with error handling that skips unsupported formats. This mirrors the CLI behavior.

```php
$formats = ['json_unescaped', 'csv'];
foreach ($formats as $format) {
    try {
        $converter = $factory->create($format);
        saveConversion($converter->convert($countries));
    } catch (\InvalidArgumentException $exception) {
        printf('Skipping %s format: %s\n', $format, $exception->getMessage());
    }
}
```

--------------------------------

### Basic usage: convert to YAML

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/yaml-converter.md

Shows how to instantiate YamlConverter and convert an array of countries to YAML, then write it to a file.

```php
use MLD\Converter\YamlConverter;

$converter = new YamlConverter();

$yaml = $converter->convert($countries);
file_put_contents('dist/countries.yml', $yaml);
```

--------------------------------

### Instantiate and configure application programmatically

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/export-command.md

Use this PHP code to create an application with the ExportCommand, specifying the input file, output directory, and default command. It requires the autoload file and uses Symfony Console's Application class.

```php
require_once 'vendor/autoload.php';

use MLD\Console\Command\ExportCommand;
use Symfony\Component\Console\Application;

$application = new Application();
$application->add(new ExportCommand(
    getcwd() . DIRECTORY_SEPARATOR . 'countries.json',
    getcwd() . DIRECTORY_SEPARATOR . 'dist',
    'convert' // default
));
$application->run();
```

--------------------------------

### create() method implementation

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/converter-factory.md

Implements the create() method that returns a converter instance based on the format string. Throws InvalidArgumentException for unsupported formats.

```php
public function create(string $format): ConverterInterface
{
    return match ($format) {
        Formats::CSV->value => new CsvConverter(),
        Formats::JSON->value => new JsonConverter(),
        Formats::JSON_UNESCAPED->value => new JsonConverterUnicode(),
        Formats::XML->value => new XmlConverter(),
        Formats::YAML->value => new YamlConverter(),
        default => throw new InvalidArgumentException(sprintf('Unsupported format %s', $format)),
    };
}
```

--------------------------------

### Composition with the factory

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/converter-interface.md

Demonstrates obtaining a converter instance via MLD\Converter\Factory::create('yml') and using it to convert countries data to YAML.

```php
use MLD\Converter\Factory;
use MLD\Converter\ConverterInterface;

$factory = new Factory();
ConverterInterface $converter = $factory->create('yml');
$yaml = $converter->convert($countries);
```

--------------------------------

### Basic usage: create a converter per format

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/converter-factory.md

Shows how to instantiate Factory and create a converter for the 'csv' format, then convert data. Requires the MLD\Converter\Factory class.

```php
use MLD\Converter\Factory;

$factory = new Factory();
$converter = $factory->create('csv');
$csv = $converter->convert($countries);
```

--------------------------------

### Basic usage: convert to CSV

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/csv-converter.md

Shows how to instantiate CsvConverter and convert an array of countries to CSV, then write to a file. Guard against empty input to avoid errors.

```php
use MLD\Converter\CsvConverter;

$converter = new CsvConverter();

$csv = $converter->convert($countries);
file_put_contents('dist/countries.csv', $csv);
```

--------------------------------

### Specify formats and output directory

Source: https://github.com/mledoze/countries/blob/master/_autodocs/configuration.md

Creates an output directory and converts to specific formats (json_unescaped and csv) into that directory.

```sh
mkdir foobar
php countries.php convert --format=json_unescaped --format=csv
php countries.php convert -f json_unescaped -f csv --output-dir=foobar
```

--------------------------------

### CLI convert command

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/countries-php-cli.md

Documentation for the `convert` CLI command provided by the `countries.php` executable.

```APIDOC
## [CLI] countries.php convert

### Description
Converts the countries dataset into one or more output formats (CSV, JSON, XML, YAML) using the `convert` command of the Symfony Console application. Options control field inclusion/exclusion, output directory, and formats.

### Method
CLI command

### Endpoint
`php countries.php convert`

### Parameters
#### Options
- **--exclude-field** (`-x`) (array, repeated) - Optional - Exclude specified fields from the output.
- **--include-field** (`-i`) (array, repeated) - Optional - Include only specified fields in the output. Mutually exclusive with `--exclude-field`.
- **--format** (`-f`) (array, repeated) - Optional - Output format(s) to generate. Supported: `csv`, `json`, `json_unescaped`, `xml`, `yml`.
- **--output-dir** (single value) - Optional - Directory where output files are written. Defaults to `dist`.

### Request Example
```sh
php countries.php convert --exclude-field=tld --format=json_unescaped --format=csv --output-dir=foobar
```

### Response
#### Success Response (exit code 0)
- Conversion completed. Output files written to the output directory.

#### Response Example
```
(no output on success)
```

#### Error Response (exit code 1)
- The input `countries.json` failed to decode (JsonException).

#### Error Response Example
```
(JSON decode error message)
```

### Notes
- Invalid format names are skipped with a warning: `Skipping <format> format: <message>`.
- `--include-field` and `--exclude-field` are mutually exclusive; `excludeFields` takes precedence.
```

--------------------------------

### Error handling for convert()

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/yaml-converter.md

Shows how to catch exceptions from the Dumper dependency when converting, printing an error message.

```php
use MLD\Converter\YamlConverter;

$converter = new YamlConverter();
try {
    $yaml = $converter->convert($countries);
} catch (\Exception $exception) {
    printf('YAML dump failed: %s\n', $exception->getMessage());
}
```

--------------------------------

### Iterate all formats with Factory

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/formats.md

Loops over all format values, creates a converter via Factory for each, and writes the converted data to 'dist/countries.<format>'. Note: for 'json_unescaped' this produces 'countries.json_unescaped', not the CLI's 'countries-unescaped.json'.

```php
use MLD\Enum\Formats;
use MLD\Converter\Factory;

$factory = new Factory();
foreach (Formats::values() as $format) {
    $converter = $factory->create($format);
    file_put_contents('dist/countries.' . $format, $converter->convert($countries));
}
```

--------------------------------

### XML export of countries data

Source: https://github.com/mledoze/countries/blob/master/README.md

XML export of the countries dataset, starting with the XML declaration and the root <countries> element. The snippet is truncated in the source; the full document would contain country entries as child elements.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<countries>
```

--------------------------------

### Basic usage: type-hint a converter

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/converter-interface.md

Shows how to type-hint the ConverterInterface in a function to accept any converter implementation.

```php
use MLD\Converter\ConverterInterface;

function convertToFormat(ConverterInterface $converter, array $countries): string
{
    return $converter->convert($countries);
}
```

--------------------------------

### ExportCommand::__construct

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/export-command.md

Constructor for the ExportCommand class. Initializes the input file, default output directory, and command name, and creates the converter factory.

```APIDOC
## ExportCommand::__construct

### Description
Constructor for the ExportCommand class. Initializes the input file, default output directory, and command name, and creates the converter factory.

### Method
Constructor

### Signature
public function __construct($inputFile, string $defaultOutputDirectory, string|null $name = 'convert')

### Parameters
- **$inputFile** (untyped; effectively string) - Required - Full path and filename of the input country data JSON file
- **$defaultOutputDirectory** (string) - Required - Full path to output directory for converted files (used when `--output-dir` is absent)
- **$name** (string|null) - Optional - Default: `'convert'` - Name of the export command, passed to `parent::__construct($name)`

### Throws
- **LogicException** (Symfony) - Propagated from the parent command constructor (`parent::__construct($name)`); e.g. a duplicate command name registration. Documented via `@throws LogicException` in the docblock.

### Behavior
Stores `$inputFile` and `$defaultOutputDirectory`, instantiates `$converterFactory = $this->createConverterFactory()` (which simply `return new Factory();`, line 158-166), then delegates to the Symfony parent constructor.
```

--------------------------------

### Full pipeline through Factory with error handling

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/json-converter.md

Full pipeline using the factory to create a JsonConverter, with error handling for unsupported formats and encoding failures. Demonstrates catching InvalidArgumentException and JsonException.

```php
use MLD\Converter\Factory;
use InvalidArgumentException;

$factory = new Factory();
try {
    $converter = $factory->create('json'); // JsonConverter
    $json = $converter->convert($countries);
    file_put_contents('out/countries.json', $json);
} catch (InvalidArgumentException $exception) {
    printf('Unsupported format: %s\n', $exception->getMessage());
} catch (JsonException $exception) {
    printf('Encode failure: %s\n', $exception->getMessage());
}
```

--------------------------------

### Exclude fields with --exclude-field and -x

Source: https://github.com/mledoze/countries/blob/master/_autodocs/configuration.md

Shows how to exclude specific fields from the output using the --exclude-field flag or its shorthand -x.

```sh
php countries.php convert --exclude-field=tld
php countries.php convert -x tld -x cca2
```

--------------------------------

### Include fields with -i

Source: https://github.com/mledoze/countries/blob/master/_autodocs/configuration.md

Shows how to include only specific fields using the -i flag.

```sh
php countries.php convert -i name -i area
```

--------------------------------

### Basic XML conversion with XmlConverter

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/xml-converter.md

Instantiates the XmlConverter and converts the $countries array to XML, saving the result to 'dist/countries.xml'.

```php
use MLD\Converter\XmlConverter;

$converter = new XmlConverter();

$xml = $converter->convert($countries);
file_put_contents('dist/countries.xml', $xml);
```

--------------------------------

### convert()

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/abstract-json-converter.md

Documentation for the convert() method of the AbstractJsonConverter class.

```APIDOC
## convert()

### Description
Converts an array of country data into a JSON document. It normalizes empty arrays to empty objects and inserts a newline between top-level array elements for readability.

### Method
convert

### Signature
public function convert(array $countries): string

### Parameters
- **$countries** (array) - Required - Countries data array (associative-array maps)

### Return Type
string - A JSON document with each country object on its own line.

### Throws
- **JsonException** - Propagated from the subclass `jsonEncode()` when the JSON encoder fails.

### Example Output
```json
[
{
  "name": {"common": "Aruba", ...}
},
{
  "name": {"common": "Afghanistan", ...}
}
]
```
```

--------------------------------

### Error handling: guard against unsupported values

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/enum-values.md

Demonstrates using Formats::values() with a Factory to create converters, catching InvalidArgumentException for unsupported formats. The loop prints a message for each unsupported format.

```php
use MLD\Enum\Formats;
use MLD\Converter\Factory;
use InvalidArgumentException;

$factory = new Factory();
foreach (Formats::values() as $format) {
    try {
        $converter = $factory->create($format);
        // conversion...
    } catch (InvalidArgumentException $exception) {
        printf('Skipping %s: %s\n', $format, $exception->getMessage());
    }
}
```

--------------------------------

### XmlConverter constructor

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/xml-converter.md

Constructor that initializes the DOM document. No parameters. Throws DOMException if initialization fails.

```php
public function __construct()
{
    $this->initializeDomDocument();
}
```

--------------------------------

### ExportCommand constructor signature

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/export-command.md

Constructor signature for ExportCommand. Accepts input file path, default output directory, and optional command name (default 'convert').

```php
public function __construct($inputFile, string $defaultOutputDirectory, string|null $name = 'convert')
```

--------------------------------

### index.mjs entry point (ES module)

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/js-entry-point.md

The ES module entry point that re-exports the default from countries.json. Used with `import countries from 'world-countries'`.

```javascript
export { default } from './countries.json';
```

--------------------------------

### Select output formats with --format or -f

Source: https://github.com/mledoze/countries/blob/master/README.md

Generates only the specified output formats. Here, JSON unescaped and CSV formats are selected.

```sh
mkdir foobar
php countries.php convert --format=json_unescaped --format=csv

# or using the shorter `-f` syntax:
php countries.php convert -f json_unescaped -f csv
```

--------------------------------

### flatten() with custom prefix and separator

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/abstract-converter.md

Shows how to call flatten() with a custom prefix and key separator. The resulting keys use the given prefix and separator, e.g. 'country_name_common'.

```php
// custom separator and prefix
$flat = $this->flatten($country, 'country_', '_');
// 'country_name_common', 'country_tld', ...
```

--------------------------------

### Basic JSON conversion with JsonConverter

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/abstract-json-converter.md

Creates a JsonConverter instance and converts an array of countries to JSON, writing the result to 'countries.json'.

```php
use MLD\Converter\JsonConverter;

$converter = new JsonConverter();

$json = $converter->convert($countries);
file_put_contents('countries.json', $json);
```

--------------------------------

### Full source of countries.php

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/countries-php-cli.md

The complete 18-line PHP script that serves as the Composer bin entry. It requires the vendor autoloader, creates a Symfony Console Application, adds the ExportCommand with the input file and default output directory, and runs the application.

```php
#!/usr/bin/env php
<?php
require_once 'vendor/autoload.php';

/**
 * Tools to convert countries in different formats
 * @author mledoze
 * @see https://github.com/mledoze/countries
 */

use MLD\Console\Command\ExportCommand;
use Symfony\Component\Console\Application;

$application = new Application();
$application->add(new ExportCommand(
	__DIR__ . DIRECTORY_SEPARATOR . 'countries.json',
	__DIR__ . DIRECTORY_SEPARATOR . 'dist'
));
$application->run();
```

--------------------------------

### convert() method implementation

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/abstract-json-converter.md

Implements ConverterInterface::convert(). It normalizes empty arrays to empty objects, then encodes the data and post-processes the output to place each country object on its own line by expanding '},{' to '},\n{'. A trailing PHP_EOL is appended. Throws JsonException if the subclass encoder fails with JSON_THROW_ON_ERROR.

```php
public function convert(array $countries): string
{
    $countries = $this->processEmptyArrays($countries);
    return preg_replace(
        '@},{@',
        sprintf('},%s{', PHP_EOL),
        $this->jsonEncode($countries) . PHP_EOL
    );
}
```

--------------------------------

### index.cjs entry point (CommonJS)

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/js-entry-point.md

The CommonJS entry point that re-exports the raw countries.json data. Used with `require('world-countries')`.

```javascript
module.exports = require('./countries.json');
```

--------------------------------

### ExportCommand constants and properties

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/export-command.md

Defines class constants and properties for ExportCommand. Includes output filename base, exit codes, and properties for input file, output directory, and converter factory.

```php
private const BASE_OUTPUT_FILENAME = 'countries';
private const EXIT_FAILURE = 1;
private const EXIT_SUCCESS = 0;

private string $inputFile;

private ?string $outputDirectory;

private Factory $converterFactory;
```

--------------------------------

### Exclude multiple fields with --exclude-field or -x

Source: https://github.com/mledoze/countries/blob/master/README.md

Shows two equivalent ways to exclude multiple fields: using the long --exclude-field flag or the shorter -x syntax.

```sh
php countries.php convert --exclude-field=tld --exclude-field=cca2

# Or using the shorter `-x` syntax:
php countries.php convert -x tld -x cca2
```

--------------------------------

### Handle unsupported format via converter factory

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/export-command.md

Use this PHP code to create a converter for a given format and catch an InvalidArgumentException if the format is unsupported. It prints an error message and continues.

```php
use MLD\Converter\Factory;

$factory = new Factory();
try {
    $converter = $factory->create('toml');
} catch (InvalidArgumentException $exception) {
    printf("Unsupported format: %s\n", $exception->getMessage());
    // "Unsupported format toml"
}
```

--------------------------------

### Use ConverterInterface to write converted data to a file

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/abstract-converter.md

Shows a function that accepts any ConverterInterface implementation, calls convert() on the countries array, and writes the result to a file using file_put_contents(). This is the typical usage pattern for converters.

```php
use MLD\Converter\ConverterInterface;

function write(ConverterInterface $converter, array $countries, string $filename): void
{
    file_put_contents($filename, $converter->convert($countries));
}
```

--------------------------------

### Include only specific fields with --include-field or -i

Source: https://github.com/mledoze/countries/blob/master/README.md

Converts data including only the specified fields. Cannot be combined with --exclude-field.

```sh
php countries.php convert --include-field=name --include-field=area

# or using the shorter `-i` syntax:
php countries.php convert -i name -i area
```

--------------------------------

### List all dataset fields with Fields::values()

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/fields.md

Lists every dataset field by calling Fields::values(), which returns an array of all enum values in declaration order. The output includes the three sub-field keys (native, root, suffixes) after the main fields.

```php
use MLD\Enum\Fields;

$fields = Fields::values();
// ['altSpellings', 'area', 'borders', 'callingCodes', 'capital', 'cca2',
//  'cca3', 'ccn3', 'cioc', 'currencies', 'demonyms', 'flag', 'idd',
//  'independent', 'landlocked', 'languages', 'latlng', 'name', 'region',
//  'status', 'subregion', 'tld', 'translations', 'unMember', 'native',
//  'root', 'suffixes']
```

--------------------------------

### Comparing JsonConverter and JsonConverterUnicode output

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/json-converter-unicode.md

Demonstrates the difference in output between the standard JsonConverter and the Unicode-preserving JsonConverterUnicode.

```php
use MLD\Converter\JsonConverter;
use MLD\Converter\JsonConverterUnicode;

$escaped = (new JsonConverter())->convert($countries);
$unescaped = (new JsonConverterUnicode())->convert($countries);

// Austrian record:
// escaped:   "...\"flag\":\"\\ud83c\\udde6\\ud83c\\uddf9\"..."
// unescaped: "...\"flag\":\"🇦🇹\"..."
```

--------------------------------

### Error handling: defensive check before parsing

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/csv-converter.md

Demonstrates a defensive check before calling convert() to avoid dereferencing an absent first element when the input array is empty.

```php
use MLD\Converter\CsvConverter;

$converter = new CsvConverter();
if (!empty($countries)) {
    $csv = $converter->convert($countries);
} else {
    printf('Nothing to convert\n');
}
```

--------------------------------

### convert() method implementation

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/yaml-converter.md

Implements ConverterInterface::convert() to dump the countries array to YAML using Symfony's Dumper with the INLINE_LEVEL.

```php
public function convert(array $countries): string
{
    return (new Dumper())->dump($countries, self::INLINE_LEVEL);
}
```

--------------------------------

### Composer script alias for convert

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/countries-php-cli.md

Defines a Composer script alias so the same run can be executed with `composer convert`.

```json
"scripts": {
    "convert": "@php countries.php convert"
}
```

--------------------------------

### Reading option values via input interface

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/export-command-options.md

Shows how to retrieve the values of the FORMAT, EXCLUDE_FIELD, and OUTPUT_DIR options using the ExportCommandOptions enum in a Symfony command context.

```php
use MLD\Enum\ExportCommandOptions;

// inside a Symfony command context
$formats = $input->getOption(ExportCommandOptions::FORMAT->value);
$excluded = $input->getOption(ExportCommandOptions::EXCLUDE_FIELD->value);
$outputDir = $input->getOption(ExportCommandOptions::OUTPUT_DIR->value);
```

--------------------------------

### Basic conversion of canonical dataset with output

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/json-converter.md

Basic usage: reads the canonical countries.json, converts it with JsonConverter, and writes the escaped JSON output. The output shows records separated by newlines (abridged).

```php
use MLD\Converter\JsonConverter;
use MACE\function file_get_contents; // dialect io helper

$countries = json_decode(file_get_contents('countries.json'), true, 512, JSON_THROW_ON_ERROR);
$converter = new JsonConverter();

$json = $converter->convert($countries);
file_put_contents('dist/countries.json', $json);
```

```json
[
{"name":{"common":"Aruba","official":"Aruba",...}}
,
{"name":{"common":"Afghanistan",...}}
]
```

--------------------------------

### convert()

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/converter-interface.md

Converts the countries data array into a serialized string in the target format. This is the single method defined by the ConverterInterface and must be implemented by all converters.

```APIDOC
## `convert(array $countries): string`

### Description
Converts countries data (an array of country associative arrays, as decoded from the canonical JSON file) into a serialized string in the target format (JSON, CSV, XML, or YAML). This is the single method defined by the ConverterInterface.

### Method
`convert`

### Signature
`public function convert(array $countries): string`

### Parameters
- **$countries** (array) - Required - Countries data: an array of country associative arrays (maps), as decoded from the canonical JSON file. `ExportCommand::decodeInputFile()` produces it with `json_decode(..., true, 512, JSON_THROW_ON_ERROR)`.

### Return Type
- **string** - The complete serialized document in the target format (JSON text, CSV text, XML document, or YAML stream), ready to be written to a file.

### Throws
Implementations may throw, and the interface contract does not restrict it. Each implementation's throws are documented in its own page:
- `JsonConverter` - `JsonException` (encode failure)
- `JsonConverterUnicode` - `JsonException` (encode failure)
- `XmlConverter` - `DOMException` (constructing the DOM / saving XML)
- `CsvConverter`, `YamlConverter` - none declared

### Usage Example
```php
use MLD\Converter\ConverterInterface;

function convertToFormat(ConverterInterface $converter, array $countries): string
{
    return $converter->convert($countries);
}
```

### Usage with Factory
```php
use MLD\Converter\Factory;
use MLD\Converter\ConverterInterface;

$factory = new Factory();
ConverterInterface $converter = $factory->create('yml');
$yaml = $converter->convert($countries);
```
```

--------------------------------

### convert()

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/xml-converter.md

Public method that converts an array of country data into an XML string. It processes each country, flattens its data, and serializes it as attributes of a <country> element within a <countries> root.

```APIDOC
## `convert()`

### Description
Public method that converts an array of country data into an XML string. It processes each country, flattens its data, and serializes it as attributes of a `<country>` element within a `<countries>` root.

### Method
`convert`

### Signature
```php
public function convert(array $countries): string
```

### Parameters

#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **$countries** (array) - Required - Countries data array

### Request Example
```php
$converter->convert([
    ['name' => 'France', 'code' => 'FR'],
    ['name' => 'Germany', 'code' => 'DE']
]);
```

### Response
#### Success Response (200)
- **string** - The full XML document: `<?xml version="1.0" encoding="UTF-8"?>` followed by the `<countries>` root containing one `<country>` element per input record.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<countries>
  <country name="France" code="FR"/>
  <country name="Germany" code="DE"/>
</countries>
```

### Error Handling
- **DOMException** - Thrown when DOM operations (`createElement`, `setAttribute`, `appendChild`, `saveXML`) report a failure.

### Notes
- The country map is flattened with `AbstractConverter::flatten()` (dot-path keys, `false`→`"0"`, empty arrays→`""`, arrays joined by `,`), then each key/value pair becomes an attribute via `setAttribute($key, (string)$value)`.
- `flatten()` semantics apply verbatim; see [api-reference/abstract-converter.md](abstract-converter.md). Values are cast to `string` when setting attributes.
```

--------------------------------

### Class declaration for Factory

Source: https://github.com/mledoze/countries/blob/master/_autodocs/api-reference/converter-factory.md

Declares the Factory class in the MLD\Converter namespace. This is the entry point for creating converter instances.

```php
class Factory
```
Tokens:
Raw