From a178ee32e5fa896aab47f672d5a8b8b13150e64e Mon Sep 17 00:00:00 2001 From: Attila Fulop <1162360+fulopattila122@users.noreply.github.com> Date: Sat, 23 Nov 2024 12:18:54 +0200 Subject: [PATCH] Made the ProvinceSeeder to extend the Registerable; Finished the seeders doc --- docs/seeders.md | 132 ++++++++++++++++-- src/Contracts/ProvinceSeeder.php | 6 +- .../database/seeds/CountiesOfHungary.php | 2 +- .../database/seeds/CountiesOfRomania.php | 2 +- .../seeds/ProvincesAndRegionsOfBelgium.php | 2 +- .../seeds/ProvincesAndTerritoriesOfCanada.php | 2 +- .../ProvincesAndTerritoriesOfCanadaFrench.php | 2 +- .../database/seeds/ProvincesOfIndonesia.php | 2 +- .../database/seeds/ProvincesOfNetherlands.php | 2 +- .../seeds/StatesAndTerritoriesOfIndia.php | 2 +- .../database/seeds/StatesOfGermany.php | 2 +- src/resources/database/seeds/StatesOfUsa.php | 2 +- 12 files changed, 133 insertions(+), 25 deletions(-) diff --git a/docs/seeders.md b/docs/seeders.md index ecf3c33..89ae4b7 100644 --- a/docs/seeders.md +++ b/docs/seeders.md @@ -77,17 +77,129 @@ Countries::byCode('nope'); // NULL ``` -## Provinces Seeder +## Provinces Seeders + +All province seeders implement the ProvinceSeeder interface, which define 4 methods. + +#### Country Code of the Seeder + +The static `getCountryCode()` method returns the country for which the seeder contains data. + +```php +StatesAndTerritoriesOfIndia::getCountryCode(); +// 'IN' +``` + +#### The Contained Province Types + +The `getProvinceTypes()` static method returns an array of [ProvinceType](province-type.md) enum objects. + +```php +StatesOfUsa::getProvinceTypes(); +//= [ +// Konekt\Address\Models\ProvinceType {#7780}, +// Konekt\Address\Models\ProvinceType {#7782}, +// Konekt\Address\Models\ProvinceType {#7784}, +// Konekt\Address\Models\ProvinceType {#7775}, +// ] + +array_map(fn($t) => $t->value(), StatesOfUsa::getProvinceTypes()); +//= [ +// "state", +// "federal_district", +// "military", +// "territory", +// ] +``` + +### The Title of the Seeder + +The static `getName()` method returns a human-readable title of the seeder. + +```php +StatesOfUsa::getName(); +//= "States, territories and other districts of the USA" +``` + +### Running the Seeder + +The `run()` method (non-static) of a seeder is the [Laravel-standard method](https://laravel.com/docs/11.x/seeding#writing-seeders) +that inserts the records in the appropriate database tables. + +## Province Seeder Registry 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 +For this purpose, the `ProvinceSeeders` registry class is available. It can be used to list, create and add new province +seeders to the system. -A sample province seeder class: +### Return Seeders + +To get the **list of seeders** available use the `ids()` method: + +```php +use \Konekt\Address\Seeds\ProvinceSeeders; + +ProvinceSeeders::ids(); +//= [ +// "counties_of_hungary", +// "counties_of_romania", +// "provinces_and_regions_of_belgium", +// "provinces_and_territories_of_canada", +// "provinces_and_territories_of_canada_french", +// "provinces_of_indonesia", +// "provinces_of_netherlands", +// "states_and_territories_of_india", +// "states_of_germany", +// "states_of_usa", +// ] +``` + +To **obtain an instance** of a given seeder, use the registry's `make()` method, passing the registered seeder ID: + +```php +$belgiumSeeder = ProvinceSeeders::make('provinces_and_regions_of_belgium'); +//= Konekt\Address\Seeds\ProvincesAndRegionsOfBelgium {#7788} +``` + +To get the available province **seeders of a country**, use the following code: + +```php +ProvinceSeeders::availableSeedersOfCountry('NL'); +//= [ +// "provinces_of_netherlands" => "Konekt\Address\Seeds\ProvincesOfNetherlands", +// ] +``` + +The `choices()` method returns a list of key/value pairs, where the key is the seeder ID and the value is the +human-readable name of the seeders: + +```php +ProvinceSeeders::choices(); +//=[ +// "counties_of_hungary" => "Counties of Hungary" +// "counties_of_romania" => "Counties of Romania" +// "provinces_and_regions_of_belgium" => "Provinces and Regions of Belgium" +// "provinces_and_territories_of_canada" => "Provinces and Territories of Canada (English)" +// "provinces_and_territories_of_canada_french" => "Provinces and Territories of Canada (French)" +// "provinces_of_indonesia" => "Provinces and Regions of Indonesia" +// "provinces_of_netherlands" => "Provinces of the Netherlands" +// "states_and_territories_of_india" => "States and Territories of India" +// "states_of_germany" => "States of Germany" +// "states_of_usa" => "States, territories and other districts of the USA" +//] +```` + +### Extending Province Seeders + +**This package doesn't come with the provinces of all countries**, only offers a limited set of them. + +But it is possible to write extensions for specific countries and register them. + +A sample custom province seeder class: ```php class RegionsOfAbsurdistan extends Seeder implements ProvinceSeeder @@ -98,7 +210,7 @@ class RegionsOfAbsurdistan extends Seeder implements ProvinceSeeder protected static array $provinceTypes = [ProvinceType::REGION] - public static function getTitle(): string + public static function getName(): string { return __('Regions of the Imaginary Absurdistan'); } @@ -110,7 +222,7 @@ class RegionsOfAbsurdistan extends Seeder implements ProvinceSeeder } ``` -To register the seeder use the following code, most commonly in the package's ServiceProvider or the app's AppServiceProvider class: +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() @@ -119,12 +231,10 @@ public function boot() } ``` -### Obtain the Province Seeders of a Country - -To get the available province seeders of a country, use the following code: +Afterward, the province seeder will be available for the country: ```php -\Konekt\Address\Seeds\ProvinceSeeders::availableSeedersOfCountry('AB'); +ProvinceSeeders::availableSeedersOfCountry('AB'); // ['regions-of-absurdistan' => 'Namespace\\RegionsOfAbsurdistan'] // Create the seeder: @@ -132,5 +242,3 @@ $seeder = ProvinceSeeders::make('regions-of-absurdistan'); // To create the provinces: $seeder->run(); ``` - - diff --git a/src/Contracts/ProvinceSeeder.php b/src/Contracts/ProvinceSeeder.php index b40168a..e03a9b7 100644 --- a/src/Contracts/ProvinceSeeder.php +++ b/src/Contracts/ProvinceSeeder.php @@ -4,7 +4,9 @@ namespace Konekt\Address\Contracts; -interface ProvinceSeeder +use Konekt\Extend\Contracts\Registerable; + +interface ProvinceSeeder extends Registerable { public static function getCountryCode(): string; @@ -13,7 +15,5 @@ public static function getCountryCode(): string; */ public static function getProvinceTypes(): array; - public static function getTitle(): string; - public function run(): void; } diff --git a/src/resources/database/seeds/CountiesOfHungary.php b/src/resources/database/seeds/CountiesOfHungary.php index cef1a35..5e63bd5 100644 --- a/src/resources/database/seeds/CountiesOfHungary.php +++ b/src/resources/database/seeds/CountiesOfHungary.php @@ -26,7 +26,7 @@ class CountiesOfHungary extends Seeder implements ProvinceSeeder protected static array $provinceTypes = [ProvinceType::COUNTY]; - public static function getTitle(): string + public static function getName(): string { return __('Counties of Hungary'); } diff --git a/src/resources/database/seeds/CountiesOfRomania.php b/src/resources/database/seeds/CountiesOfRomania.php index 3db5766..74baeac 100644 --- a/src/resources/database/seeds/CountiesOfRomania.php +++ b/src/resources/database/seeds/CountiesOfRomania.php @@ -26,7 +26,7 @@ class CountiesOfRomania extends Seeder implements ProvinceSeeder protected static array $provinceTypes = [ProvinceType::COUNTY]; - public static function getTitle(): string + public static function getName(): string { return __('Counties of Romania'); } diff --git a/src/resources/database/seeds/ProvincesAndRegionsOfBelgium.php b/src/resources/database/seeds/ProvincesAndRegionsOfBelgium.php index 9216828..64cb88f 100644 --- a/src/resources/database/seeds/ProvincesAndRegionsOfBelgium.php +++ b/src/resources/database/seeds/ProvincesAndRegionsOfBelgium.php @@ -26,7 +26,7 @@ class ProvincesAndRegionsOfBelgium extends Seeder implements ProvinceSeeder protected static array $provinceTypes = [ProvinceType::REGION, ProvinceType::PROVINCE]; - public static function getTitle(): string + public static function getName(): string { return __('Provinces and Regions of Belgium'); } diff --git a/src/resources/database/seeds/ProvincesAndTerritoriesOfCanada.php b/src/resources/database/seeds/ProvincesAndTerritoriesOfCanada.php index bc2ee0f..11d2b57 100644 --- a/src/resources/database/seeds/ProvincesAndTerritoriesOfCanada.php +++ b/src/resources/database/seeds/ProvincesAndTerritoriesOfCanada.php @@ -27,7 +27,7 @@ class ProvincesAndTerritoriesOfCanada extends Seeder implements ProvinceSeeder protected static array $provinceTypes = [ProvinceType::PROVINCE, ProvinceType::TERRITORY]; - public static function getTitle(): string + public static function getName(): string { return __('Provinces and Territories of Canada (English)'); } diff --git a/src/resources/database/seeds/ProvincesAndTerritoriesOfCanadaFrench.php b/src/resources/database/seeds/ProvincesAndTerritoriesOfCanadaFrench.php index 1e86848..fc79c5f 100644 --- a/src/resources/database/seeds/ProvincesAndTerritoriesOfCanadaFrench.php +++ b/src/resources/database/seeds/ProvincesAndTerritoriesOfCanadaFrench.php @@ -27,7 +27,7 @@ class ProvincesAndTerritoriesOfCanadaFrench extends Seeder implements ProvinceSe protected static array $provinceTypes = [ProvinceType::PROVINCE, ProvinceType::TERRITORY]; - public static function getTitle(): string + public static function getName(): string { return __('Provinces and Territories of Canada (French)'); } diff --git a/src/resources/database/seeds/ProvincesOfIndonesia.php b/src/resources/database/seeds/ProvincesOfIndonesia.php index f1ac037..38e4529 100644 --- a/src/resources/database/seeds/ProvincesOfIndonesia.php +++ b/src/resources/database/seeds/ProvincesOfIndonesia.php @@ -26,7 +26,7 @@ class ProvincesOfIndonesia extends Seeder implements ProvinceSeeder protected static array $provinceTypes = [ProvinceType::UNIT, ProvinceType::PROVINCE, ProvinceType::REGION]; - public static function getTitle(): string + public static function getName(): string { return __('Provinces and Regions of Indonesia'); } diff --git a/src/resources/database/seeds/ProvincesOfNetherlands.php b/src/resources/database/seeds/ProvincesOfNetherlands.php index 0826c44..f8cd501 100644 --- a/src/resources/database/seeds/ProvincesOfNetherlands.php +++ b/src/resources/database/seeds/ProvincesOfNetherlands.php @@ -26,7 +26,7 @@ class ProvincesOfNetherlands extends Seeder implements ProvinceSeeder protected static array $provinceTypes = [ProvinceType::PROVINCE]; - public static function getTitle(): string + public static function getName(): string { return __('Provinces of the Netherlands'); } diff --git a/src/resources/database/seeds/StatesAndTerritoriesOfIndia.php b/src/resources/database/seeds/StatesAndTerritoriesOfIndia.php index 2bb803c..0052e89 100644 --- a/src/resources/database/seeds/StatesAndTerritoriesOfIndia.php +++ b/src/resources/database/seeds/StatesAndTerritoriesOfIndia.php @@ -26,7 +26,7 @@ class StatesAndTerritoriesOfIndia extends Seeder implements ProvinceSeeder protected static array $provinceTypes = [ProvinceType::STATE, ProvinceType::TERRITORY]; - public static function getTitle(): string + public static function getName(): string { return __('States and Territories of India'); } diff --git a/src/resources/database/seeds/StatesOfGermany.php b/src/resources/database/seeds/StatesOfGermany.php index 4d17761..b659180 100644 --- a/src/resources/database/seeds/StatesOfGermany.php +++ b/src/resources/database/seeds/StatesOfGermany.php @@ -26,7 +26,7 @@ class StatesOfGermany extends Seeder implements ProvinceSeeder protected static array $provinceTypes = [ProvinceType::STATE]; - public static function getTitle(): string + public static function getName(): string { return __('States of Germany'); } diff --git a/src/resources/database/seeds/StatesOfUsa.php b/src/resources/database/seeds/StatesOfUsa.php index 0dbc2fa..706d4d2 100644 --- a/src/resources/database/seeds/StatesOfUsa.php +++ b/src/resources/database/seeds/StatesOfUsa.php @@ -26,7 +26,7 @@ class StatesOfUsa extends Seeder implements ProvinceSeeder protected static array $provinceTypes = [ProvinceType::STATE, ProvinceType::FEDERAL_DISTRICT, ProvinceType::MILITARY, ProvinceType::TERRITORY]; - public static function getTitle(): string + public static function getName(): string { return __('States, territories and other districts of the USA'); }