Add Finder::getProvinceByVehicleCode() (#8)

README.md

@@ -80,7 +80,7 @@ This library provides the following data:
   - the second level of the current Nomenclature of Territorial Units for Statistics (NUTS2) (example: `'ITC1'`)
   - the third level of the current Nomenclature of Territorial Units for Statistics (NUTS3) (example: `'ITC11'`)
 
-### Retrieving Territories
+### Retrieving All Territories
 
 You can have a list of all the Geographical Subdivisions, Regions, Provinces/UTS, and Municipalities using the `Factory` class.
 
@@ -97,6 +97,8 @@ $allProvinces = $factory->getProvinces();
 $allMunicipalities = $factory->getMunicipalities();
 ```
 
+### Finding Territories by ID
+
 If you want to retrieve a territory given its ID, you can use the `Finder` class:
 
 ```php
@@ -110,6 +112,19 @@ $province = $finder->getProvinceByID('201');
 $municipality = $finder->getMunicipalityByID('001272');
 ```
 
+### Finding Provinces by Vehicle Code
+
+You can use the `getProvinceByVehicleCode` method of the `Finder` class:
+
+```php
+use MLocati\ComuniItaliani\Finder;
+
+$finder = new Finder();
+
+echo $finder->getProvinceByVehicleCode('CO')->getName();
+// prints Como
+```
+
 ### Finding Territories by Name
 
 You can use the `Finder` class to find Geographical Subdivisions, Regions, Provinces/UTS, and Municipalities by name.

src/Finder.php

@@ -95,6 +95,20 @@ public function getProvinceByID(string $id, bool $oldIDToo = false): ?Province
         return null;
     }
 
+    public function getProvinceByVehicleCode(string $vehicleCode): ?Province
+    {
+        if (!preg_match('/^[A-Za-z]{2}$/', $vehicleCode)) {
+            return null;
+        }
+        $vehicleCode = strtoupper($vehicleCode);
+        foreach ($this->listProvinces() as $province) {
+            if ($province->getVehicleCode() === $vehicleCode) {
+                return $province;
+            }
+        }
+
+        return null;
+    }
 
     /**
      * Find a Municipality given its ID

test/tests/Finder/FindProvinceByVehicleCodeTest.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MLocati\ComuniItaliani\Test\Finder;
+
+use MLocati\ComuniItaliani\Finder;
+use MLocati\ComuniItaliani\Province;
+use PHPUnit\Framework\TestCase;
+
+class FindProvinceByVehicleCodeTest extends TestCase
+{
+    private static ?Finder $finder;
+
+    public function provideGetProvinceByVehicleCodeCases(): array
+    {
+        return [
+            ['', ''],
+            ['0', ''],
+            ['1', ''],
+            ['AA', ''],
+            ['AAAAAAA', ''],
+            ['99', ''],
+            ['Co', 'Como'],
+            ['cO', 'Como'],
+            ['co', 'Como'],
+            ['CO', 'Como'],
+            ['RM', 'Roma'],
+        ];
+    }
+
+    /**
+     * @dataProvider provideGetProvinceByVehicleCodeCases
+     */
+    public function testGetProvinceByVehicleCode(string $vehicleCode, string $expectedName): void
+    {
+        $province = $this->getFinder()->getProvinceByVehicleCode($vehicleCode);
+        if ($expectedName === '') {
+            $this->assertNull($province);
+        } else {
+            $this->assertInstanceOf(Province::class, $province);
+            $this->assertSame($expectedName, (string) $province);
+        }
+    }
+
+    private function getFinder(): Finder
+    {
+        return self::$finder ??= new Finder();
+    }
+}