feat: store and serve YouTube thumbnails for heritage images

- Migration: add main_video_url column to world_heritage_sites
- Command: world-heritage:sync-video-urls fetches main_video_url from
  data.unesco.org API and populates DB (1248 records synced)
- Model: add main_video_url to WorldHeritage fillable
- Controller: look up main_video_url from DB instead of calling UNESCO
  API on every request, then proxy YouTube hqdefault thumbnail

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: zigzagdev

src/app/Console/Commands/SyncWorldHeritageVideoUrls.php

@@ -0,0 +1,96 @@
+<?php
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Http;
+
+class SyncWorldHeritageVideoUrls extends Command
+{
+    protected $signature = 'world-heritage:sync-video-urls
+        {--limit=100 : Records per API request}
+        {--dry-run : Show counts without updating DB}';
+
+    protected $description = 'Fetch main_video_url from data.unesco.org API and update world_heritage_sites';
+
+    private const API_URL = 'https://data.unesco.org/api/explore/v2.1/catalog/datasets/whc001/records';
+
+    public function handle(): int
+    {
+        $limit   = max(1, (int) $this->option('limit'));
+        $dryRun  = (bool) $this->option('dry-run');
+
+        $first = $this->fetch(1, 0);
+        if ($first === null) {
+            return self::FAILURE;
+        }
+
+        $total   = (int) ($first['total_count'] ?? 0);
+        $offset  = 0;
+        $updated = 0;
+        $skipped = 0;
+
+        $this->info("Total UNESCO records: {$total}");
+
+        while ($offset < $total) {
+            $response = $this->fetch($limit, $offset);
+            if ($response === null) {
+                return self::FAILURE;
+            }
+
+            $results = $response['results'] ?? [];
+            if ($results === []) {
+                break;
+            }
+
+            foreach ($results as $row) {
+                $idNo     = (int) ($row['id_no'] ?? 0);
+                $videoUrl = $row['main_video_url'] ?? null;
+
+                if ($idNo === 0) {
+                    $skipped++;
+                    continue;
+                }
+
+                if (!$dryRun) {
+                    DB::table('world_heritage_sites')
+                        ->where('id', $idNo)
+                        ->update(['main_video_url' => $videoUrl]);
+                }
+
+                $updated++;
+            }
+
+            $offset += count($results);
+            $this->line("Processed {$offset}/{$total}...");
+        }
+
+        if ($dryRun) {
+            $this->info("Dry-run: would update {$updated} records, skipped {$skipped}.");
+        } else {
+            $this->info("Done. Updated {$updated} records, skipped {$skipped}.");
+        }
+
+        return self::SUCCESS;
+    }
+
+    private function fetch(int $limit, int $offset): ?array
+    {
+        $response = Http::acceptJson()
+            ->retry(3, 500)
+            ->get(self::API_URL, [
+                'select'   => 'id_no,main_video_url',
+                'limit'    => $limit,
+                'offset'   => $offset,
+                'order_by' => 'id_no asc',
+            ]);
+
+        if ($response->failed()) {
+            $this->error("UNESCO API error: HTTP {$response->status()} offset={$offset}");
+            return null;
+        }
+
+        return $response->json();
+    }
+}

src/app/Models/WorldHeritage.php

@@ -36,6 +36,7 @@ class WorldHeritage extends Model
         'short_description',
         'unesco_site_url',
         'main_image_url',
+        'main_video_url',
     ];
 
     protected $hidden = [

src/app/Packages/Features/Controller/HeritageImageController.php

@@ -4,6 +4,7 @@
 
 use App\Http\Controllers\Controller;
 use App\Models\Image;
+use App\Models\WorldHeritage;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
 use Illuminate\Http\JsonResponse;
@@ -37,20 +38,9 @@ public function proxyImage(Request $request, int $id): Response|JsonResponse
 
     private function fetchVideoUrlFromUnesco(int $idNo): ?string
     {
-        $response = Http::acceptJson()
-            ->get('https://data.unesco.org/api/explore/v2.1/catalog/datasets/whc001/records', [
-                'where' => "id_no={$idNo}",
-                'limit' => 1,
-                'select' => 'main_video_url',
-            ]);
-
-        if ($response->failed()) {
-            return null;
-        }
-
-        $results = $response->json('results');
+        $site = WorldHeritage::find($idNo);
 
-        return $results[0]['main_video_url'] ?? null;
+        return $site?->main_video_url;
     }
 
     private function buildYoutubeThumbnailUrl(string $videoUrl): ?string

src/database/migrations/2026_05_26_232121_add_main_video_url_to_world_heritage_sites.php

@@ -0,0 +1,22 @@
+<?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_heritage_sites', function (Blueprint $table) {
+            $table->string('main_video_url')->nullable()->after('main_image_url');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('world_heritage_sites', function (Blueprint $table) {
+            $table->dropColumn('main_video_url');
+        });
+    }
+};