feat(regions): implement world regions

.github/workflows/linter.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.head_ref }}
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
 
       - name: Run Laravel Pint
         uses: aglipanci/laravel-pint-action@latest

.github/workflows/test-runner.yml

@@ -41,7 +41,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.head_ref }}
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
 
       - name: Validate composer.json and composer.lock
         run: composer validate --strict

database/factories/CountryFactory.php

@@ -27,6 +27,7 @@ public function definition(): array
             'num_code' => str_pad(fake()->numberBetween(1, 999), 3, '0', STR_PAD_LEFT),
             'name' => fake()->country(),
             'flag' => fake()->emoji(),
+            'region_id' => null,
         ];
     }
 }

database/factories/CountrySpecialRegionFactory.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace Eclipse\World\Factories;
+
+use Eclipse\World\Models\Country;
+use Eclipse\World\Models\CountrySpecialRegion;
+use Eclipse\World\Models\Region;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+class CountrySpecialRegionFactory extends Factory
+{
+    /**
+     * The name of the factory's corresponding model.
+     *
+     * @var string
+     */
+    protected $model = CountrySpecialRegion::class;
+
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        return [
+            'country_id' => Country::factory(),
+            'region_id' => Region::factory()->special(),
+            'start_date' => $this->faker->dateTimeBetween('-2 years', 'now')->format('Y-m-d'),
+            'end_date' => $this->faker->optional(0.3)->dateTimeBetween('now', '+2 years')?->format('Y-m-d'),
+        ];
+    }
+
+    /**
+     * Set the region as active.
+     *
+     * @return $this
+     */
+    public function active(): static
+    {
+        return $this->state([
+            'start_date' => $this->faker->dateTimeBetween('-1 year', 'now')->format('Y-m-d'),
+            'end_date' => null,
+        ]);
+    }
+
+    /**
+     * Set the region as ended.
+     *
+     * @return $this
+     */
+    public function ended(): static
+    {
+        return $this->state([
+            'start_date' => $this->faker->dateTimeBetween('-2 years', '-6 months')->format('Y-m-d'),
+            'end_date' => $this->faker->dateTimeBetween('-6 months', 'now')->format('Y-m-d'),
+        ]);
+    }
+
+    /**
+     * Set the region as future.
+     *
+     * @return $this
+     */
+    public function future(): static
+    {
+        return $this->state([
+            'start_date' => $this->faker->dateTimeBetween('now', '+6 months')->format('Y-m-d'),
+            'end_date' => $this->faker->optional(0.5)->dateTimeBetween('+6 months', '+2 years')?->format('Y-m-d'),
+        ]);
+    }
+}

database/factories/RegionFactory.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace Eclipse\World\Factories;
+
+use Eclipse\World\Models\Region;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+class RegionFactory extends Factory
+{
+    /**
+     * The name of the factory's corresponding model.
+     *
+     * @var string
+     */
+    protected $model = Region::class;
+
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        return [
+            'code' => strtoupper($this->faker->unique()->lexify('???')),
+            'name' => $this->faker->unique()->words(2, true),
+            'is_special' => false,
+        ];
+    }
+
+    /**
+     * Set the region as special.
+     *
+     * @return $this
+     */
+    public function special(): static
+    {
+        return $this->state(['is_special' => true]);
+    }
+
+    /**
+     * Set the region as geographical.
+     *
+     * @return $this
+     */
+    public function geographical(): static
+    {
+        return $this->state(['is_special' => false]);
+    }
+
+    /**
+     * Set the region as a child of a parent region.
+     *
+     * @return $this
+     */
+    public function withParent(Region $parent): static
+    {
+        return $this->state(['parent_id' => $parent->id]);
+    }
+}

database/migrations/2025_07_26_120000_create_regions_table.php

@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('world_regions', function (Blueprint $table) {
+            $table->id();
+            $table->string('code')->nullable()->unique();
+            $table->unsignedBigInteger('parent_id')->nullable();
+            $table->boolean('is_special')->default(false);
+            $table->string('name');
+            $table->timestamps();
+            $table->softDeletes();
+
+            $table->foreign('parent_id')->references('id')->on('world_regions')->onDelete('cascade');
+            $table->index(['is_special', 'parent_id']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('world_regions');
+    }
+};

database/migrations/2025_07_26_120001_add_region_id_to_countries_table.php

@@ -0,0 +1,26 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('world_countries', function (Blueprint $table) {
+            $table->unsignedBigInteger('region_id')->nullable()->after('flag');
+            $table->foreign('region_id')->references('id')->on('world_regions')->onDelete('set null');
+            $table->index('region_id');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('world_countries', function (Blueprint $table) {
+            $table->dropForeign(['region_id']);
+            $table->dropIndex(['region_id']);
+            $table->dropColumn('region_id');
+        });
+    }
+};

database/migrations/2025_07_26_120002_create_country_in_special_region_table.php

@@ -0,0 +1,31 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('world_country_in_special_region', function (Blueprint $table) {
+            $table->id();
+            $table->string('country_id', 2);
+            $table->unsignedBigInteger('region_id');
+            $table->date('start_date');
+            $table->date('end_date')->nullable();
+            $table->timestamps();
+
+            $table->foreign('country_id')->references('id')->on('world_countries')->onDelete('cascade');
+            $table->foreign('region_id')->references('id')->on('world_regions')->onDelete('cascade');
+
+            $table->unique(['country_id', 'region_id', 'start_date'], 'unique_country_region_start');
+            $table->index(['region_id', 'start_date', 'end_date'], 'idx_region_dates');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('world_country_in_special_region');
+    }
+};

database/migrations/2025_07_26_120003_seed_eu_region.php

@@ -0,0 +1,41 @@
+<?php
+
+use Eclipse\World\Models\Country;
+use Eclipse\World\Models\Region;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Carbon;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        // Create EU special region
+        $euRegion = Region::create([
+            'code' => 'EU',
+            'name' => 'European Union',
+            'is_special' => true,
+        ]);
+
+        $euMemberCountries = [
+            'AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR',
+            'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL',
+            'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE',
+        ];
+
+        $existingCountries = Country::whereIn('id', $euMemberCountries)->pluck('id');
+        $membershipData = $existingCountries->mapWithKeys(fn ($countryId) => [
+            $countryId => [
+                'start_date' => Carbon::now()->toDateString(),
+                'created_at' => now(),
+                'updated_at' => now(),
+            ],
+        ]);
+
+        $euRegion->specialCountries()->attach($membershipData);
+    }
+
+    public function down(): void
+    {
+        Region::where('code', 'EU')->delete();
+    }
+};

resources/lang/en/countries.php

@@ -22,6 +22,12 @@
         'num_code' => [
             'label' => 'Num. Code',
         ],
+        'region' => [
+            'label' => 'Region',
+        ],
+        'special_regions' => [
+            'label' => 'Special Regions',
+        ],
     ],
 
     'actions' => [
@@ -67,6 +73,10 @@
             'label' => 'Numeric code',
             'helper' => 'Numeric code (ISO-3166)',
         ],
+        'region' => [
+            'label' => 'Geographical Region',
+            'helper' => 'The geographical region this country belongs to',
+        ],
     ],
 
     'import' => [
@@ -86,4 +96,10 @@
             'message' => 'Failed to import countries data.',
         ],
     ],
+
+    'filters' => [
+        'region' => [
+            'label' => 'Region',
+        ],
+    ],
 ];