Merge pull request #72 from sokil/country_details

add common name and flag of country

Author: sokil

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 4.2.0 (2023-06-11)
+### Added
+- Common name of country `\Sokil\IsoCodes\Database\Countries\Country::getCommonName`
+- Flag of country `\Sokil\IsoCodes\Database\Countries\Country::getFlag`
+
 ## 4.1.1 (2023-02-10)
 ### Fixes
 - Auth release fix. Swallow clone does not clone tags required to set version in README

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2013-2022 Dmytro Sokil
+Copyright (c) 2013-2023 Dmytro Sokil
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,4 +1,4 @@
-# Stand With Ukraine
+# Stand With Ukraine 🇺🇦
 
 [![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)
 
@@ -248,7 +248,7 @@ $isoCodes = new IsoCodesFactory(
 
 ### Factory
 
-All databases may be create through factory:
+All databases may be created through factory:
 
 ```php
 <?php
@@ -287,6 +287,34 @@ This may require a lot of RAM for storing all entries.
 
 ### Countries database (ISO 3166-1)
 
+Country contains next names:
+
+| Name           | Description | Example              |
+|----------------|-------------|----------------------|
+| Name           | Required    | Moldova, Republic of |
+| Official Name  | Optional    | Republic of Moldova  |
+| Common Name    | Optional    | Moldova              |
+| Localised Name | Optional    | Молдова              |
+
+This names may be get from country entity:
+
+```php
+$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
+$country = $isoCodes->getCountries()->getByAlpha2('UA');
+echo $country->getName();
+echo $country->getLocalName();
+echo $country->getOfficialName();
+echo $country->getCommonName();
+```
+
+Also you may get flag of country:
+
+```php
+$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
+$country = $isoCodes->getCountries()->getByAlpha2('UA');
+echo $country->getFlag();
+```
+
 Get localized name of country by it's alpha2 code:
 ```php
 $isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
@@ -296,13 +324,13 @@ $isoCodes->getCountries()->getByAlpha2('UA')->getLocalName();
 Get localized name of country by it's alpha2 code:
 ```php
 $isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
-$isoCodes->getCountries()->getByAlpha2('UKR')->getName();
+$isoCodes->getCountries()->getByAlpha2('UKR')->getLocalName();
 ```
 
 Get localized name of country by it's numeric code:
 ```php
 $isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
-$isoCodes->getCountries()->getByAlpha2('804')->getName();
+$isoCodes->getCountries()->getByAlpha2('804')->getLocalName();
 ```
 
 Get  localised list of countries

src/Database/Countries.php

@@ -33,7 +33,9 @@ protected function arrayToEntry(array $entry): Country
             $entry['alpha_2'],
             $entry['alpha_3'],
             $entry['numeric'],
-            !empty($entry['official_name']) ? $entry['official_name'] : null
+            $entry['flag'],
+            !empty($entry['official_name']) ? $entry['official_name'] : null,
+            !empty($entry['common_name']) ? $entry['common_name'] : null,
         );
     }
 

src/Database/Countries/Country.php

@@ -34,11 +34,23 @@ class Country
      */
     private $numericCode;
 
+    /**
+     * Emoji of country flag
+     *
+     * @var string
+     */
+    private $flag;
+
     /**
      * @var string
      */
     private $officialName;
 
+    /**
+     * @var string
+     */
+    private $commonName;
+
     /**
      * @var TranslatorInterface
      */
@@ -50,14 +62,18 @@ public function __construct(
         string $alpha2,
         string $alpha3,
         string $numericCode,
-        ?string $officialName = null
+        string $flag,
+        ?string $officialName = null,
+        ?string $commonName = null
     ) {
         $this->translator = $translator;
         $this->name = $name;
         $this->alpha2 = $alpha2;
         $this->alpha3 = $alpha3;
         $this->numericCode = $numericCode;
+        $this->flag = $flag;
         $this->officialName = $officialName;
+        $this->commonName = $commonName;
     }
 
     public function getAlpha2(): string
@@ -75,6 +91,14 @@ public function getNumericCode(): string
         return $this->numericCode;
     }
 
+    /**
+     * @return string
+     */
+    public function getFlag(): string
+    {
+        return $this->flag;
+    }
+
     public function getName(): string
     {
         return $this->name;
@@ -96,4 +120,9 @@ public function getOfficialName(): ?string
     {
         return $this->officialName;
     }
+
+    public function getCommonName(): ?string
+    {
+        return $this->commonName;
+    }
 }

tests/Database/CountriesTest.php

@@ -66,6 +66,16 @@ public function testGetByAlpha2(): void
             null,
             $country->getOfficialName()
         );
+
+        $this->assertEquals(
+            null,
+            $country->getCommonName()
+        );
+
+        $this->assertEquals(
+            '🇺🇦',
+            $country->getFlag()
+        );
     }
 
     public function testGetByAlpha3(): void