Extending the ProvinceSeeder interface + the province seeders doc

docs/seeders.md

@@ -52,12 +52,60 @@ Countries::byCode('nope');
 
 ## Provinces Seeder
 
-Besides using as a standard Laravel Seeder, the various province seeders can be used as a standalone utility classes
-to manage the provinces of the world.
-
+Besides using as a standard Laravel Seeder, the various province seeder classes can be used as a standalone utility classes
+to manage the provinces of countries.
 
 > This `ProvinceSeeders` registry was added in version `3.4.0`
 
+This package doesn't ship with the provinces of all countries, only offers a limited set of them.
+But it offers the possibility for anyone to write extensions for specific countries and register them
+
+A sample province seeder class:
+
+```php
+class RegionsOfAbsurdistan extends Seeder implements ProvinceSeeder
+{
+    use IsProvinceSeeder;
+
+    protected static string $forCountry = 'AB';
+
+    protected static array $provinceTypes = [ProvinceType::REGION]
+
+    public static function getTitle(): string
+    {
+        return __('Regions of the Imaginary Absurdistan');
+    }
+
+    public function run(): void
+    {
+        // insert the records here        
+    }
+}
+```
+
+To register the seeder use the following code, most commonly in the package's ServiceProvider or the app's AppServiceProvider class:
+
+```php
+public function boot()
+{
+    ProvinceSeeders::extend(RegionsOfAbsurdistan::class);
+}
+```
+
+### Obtain the Province Seeders of a Country
+
+To get the available province seeders of a country, use the following code:
+
+```php
+\Konekt\Address\Seeds\ProvinceSeeders::availableSeedersOfCountry('AB');
+// ['regions-of-absurdistan' => 'Namespace\\RegionsOfAbsurdistan']
+
+// Create the seeder:
+$seeder = ProvinceSeeders::make('regions-of-absurdistan');
+// To create the provinces:
+$seeder->run();
+```
+
 ## Loading
 
 ### With Artisan
@@ -81,4 +129,4 @@ class DatabaseSeeder extends \Illuminate\Database\Seeder
 ```
 
 > For more details refer to the [seeds section](https://konekt.dev/concord/1.3/seeds) in the Concord
-docs.
+> docs.

src/Contracts/ProvinceSeeder.php

@@ -12,4 +12,8 @@ public static function getCountryCode(): string;
      * @return array|ProvinceType[]
      */
     public static function getProvinceTypes(): array;
+
+    public static function getTitle(): string;
+
+    public function run(): void;
 }

src/resources/database/seeds/CountiesOfHungary.php

@@ -26,7 +26,12 @@ class CountiesOfHungary extends Seeder implements ProvinceSeeder
 
     protected static array $provinceTypes = [ProvinceType::COUNTY];
 
-    public function run()
+    public static function getTitle(): string
+    {
+        return __('Counties of Hungary');
+    }
+
+    public function run(): void
     {
         \DB::table('provinces')->insert([
             [

src/resources/database/seeds/CountiesOfRomania.php

@@ -26,12 +26,17 @@ class CountiesOfRomania extends Seeder implements ProvinceSeeder
 
     protected static array $provinceTypes = [ProvinceType::COUNTY];
 
+    public static function getTitle(): string
+    {
+        return __('Counties of Romania');
+    }
+
     /**
      * Inserts the counties of Romania into the provinces table
      *
      * @return void
      */
-    public function run()
+    public function run(): void
     {
         \DB::table('provinces')->insert([
                 [

src/resources/database/seeds/Countries.php

@@ -23,7 +23,7 @@ class Countries extends Seeder
      *
      * @return void
      */
-    public function run()
+    public function run(): void
     {
         \DB::table('countries')->delete();
 

src/resources/database/seeds/ProvincesAndRegionsOfBelgium.php

@@ -26,7 +26,12 @@ class ProvincesAndRegionsOfBelgium extends Seeder implements ProvinceSeeder
 
     protected static array $provinceTypes = [ProvinceType::REGION, ProvinceType::PROVINCE];
 
-    public function run()
+    public static function getTitle(): string
+    {
+        return __('Provinces and Regions of Belgium');
+    }
+
+    public function run(): void
     {
         \DB::table('provinces')->insert([
             "name" => "Brussels",

src/resources/database/seeds/ProvincesAndTerritoriesOfCanada.php

@@ -27,7 +27,12 @@ class ProvincesAndTerritoriesOfCanada extends Seeder implements ProvinceSeeder
 
     protected static array $provinceTypes = [ProvinceType::PROVINCE, ProvinceType::TERRITORY];
 
-    public function run()
+    public static function getTitle(): string
+    {
+        return __('Provinces and Territories of Canada (English)');
+    }
+
+    public function run(): void
     {
         DB::table('provinces')->insert([
             /** - - - - - - - - - P R O V I N C E S - - - - - - - - **/

src/resources/database/seeds/ProvincesAndTerritoriesOfCanadaFrench.php

@@ -27,7 +27,12 @@ class ProvincesAndTerritoriesOfCanadaFrench extends Seeder implements ProvinceSe
 
     protected static array $provinceTypes = [ProvinceType::PROVINCE, ProvinceType::TERRITORY];
 
-    public function run()
+    public static function getTitle(): string
+    {
+        return __('Provinces and Territories of Canada (French)');
+    }
+
+    public function run(): void
     {
         DB::table('provinces')->insert([
             /** - - - - - - - - - P R O V I N C E S - - - - - - - - **/

src/resources/database/seeds/ProvincesOfIndonesia.php

@@ -26,7 +26,12 @@ class ProvincesOfIndonesia extends Seeder implements ProvinceSeeder
 
     protected static array $provinceTypes = [ProvinceType::UNIT, ProvinceType::PROVINCE, ProvinceType::REGION];
 
-    public function run()
+    public static function getTitle(): string
+    {
+        return __('Provinces and Regions of Indonesia');
+    }
+
+    public function run(): void
     {
         $this->createJavaWithProvinces();
         $this->createKalimantanWithProvinces();

src/resources/database/seeds/ProvincesOfNetherlands.php

@@ -26,7 +26,12 @@ class ProvincesOfNetherlands extends Seeder implements ProvinceSeeder
 
     protected static array $provinceTypes = [ProvinceType::PROVINCE];
 
-    public function run()
+    public static function getTitle(): string
+    {
+        return __('Provinces of the Netherlands');
+    }
+
+    public function run(): void
     {
         \DB::table('provinces')->insert([
             [

src/resources/database/seeds/StatesAndTerritoriesOfIndia.php

@@ -26,7 +26,12 @@ class StatesAndTerritoriesOfIndia extends Seeder implements ProvinceSeeder
 
     protected static array $provinceTypes = [ProvinceType::STATE, ProvinceType::TERRITORY];
 
-    public function run()
+    public static function getTitle(): string
+    {
+        return __('States and Territories of India');
+    }
+
+    public function run(): void
     {
         \DB::table('provinces')->insert([
             [

src/resources/database/seeds/StatesOfGermany.php

@@ -26,7 +26,12 @@ class StatesOfGermany extends Seeder implements ProvinceSeeder
 
     protected static array $provinceTypes = [ProvinceType::STATE];
 
-    public function run()
+    public static function getTitle(): string
+    {
+        return __('States of Germany');
+    }
+
+    public function run(): void
     {
         \DB::table('provinces')->insert([
             [

src/resources/database/seeds/StatesOfUsa.php

@@ -26,12 +26,17 @@ class StatesOfUsa extends Seeder implements ProvinceSeeder
 
     protected static array $provinceTypes = [ProvinceType::STATE, ProvinceType::FEDERAL_DISTRICT, ProvinceType::MILITARY, ProvinceType::TERRITORY];
 
+    public static function getTitle(): string
+    {
+        return __('States, territories and other districts of the USA');
+    }
+
     /**
      * Inserts the states of USA into the provinces table
      *
      * @return void
      */
-    public function run()
+    public function run(): void
     {
         \DB::table('provinces')->insert(
             [