Bump version to 0.12.1

CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.12.1] - 2026-09-03
+
+### Fixed
+- `Modules\Core\MigrateImport\Shopify\ShopifyExportImporter` now attaches a variant's `Variant Image` CSV column to that `ProductVariant`'s own `images()` media pivot (`media_product_variant`, `primary`/`position`). Previously the variant image was never read at all — every image from the CSV, including ones the export clearly scopes to one specific variant, went only into the product's own top-level gallery, so a variant swatch/option change had no way to show its own photo.
+- `Modules\Core\MigrateImport\Shopify\Resolvers\ProductOptionResolver::resolveOption()` now sets `label` (same value as `name`) when creating a `Lunar\Models\ProductOption`, not just `name`. A `ProductOption` with a null `label` crashes Lunar's own `ProductOptionIndexer::toSearchableArray()` (`foreach()` on `null`) the moment that option gets reindexed — every option created by the importer before this fix has a null `label` and needs a wipe-and-reimport (see `docs/shopify-reimport.md`, new in this release) to pick up the fix, since `firstOrCreate()` never revisits an already-existing row.
+- `product_reviews.product_id`'s foreign key had no `ON DELETE` clause, so deleting a reviewed `Product` threw a constraint violation instead of the review going with it, unlike every other product-dependent table. New migration adds `cascadeOnDelete()`.
+
+### Added
+- `Modules\Core\Catalog\Services\ProductIndexer::mapVariant()` now embeds `gtin`, `mpn`, `ean`, `backorder`, `unit_quantity`, `shippable`, `tax_ref`, and `dimensions` (length/width/height/weight/volume, each with `value`+`unit`) on every indexed variant — previously only `id`/`sku`/`stock`/`purchasable`/`options`/`prices`/`media` were embedded, so a search result or filter needing any of these had no way to get at them without a separate Postgres query per variant.
+- `ProductIndexer::toSearchableArray()` adds a top-level, filterable `skus` field (every variant's SKU, deduplicated) — filtering/matching by SKU no longer requires reaching into the nested `variants` array.
+- `docs/shopify-reimport.md` — runbook for wiping every imported product (cascading through Lunar so Meilisearch documents go too) and re-running the importer from scratch, needed whenever a fix like the two above only takes effect on newly-created rows.
+
 ## [0.12.0] - 2026-09-03
 
 ### Changed

composer.json

@@ -2,7 +2,7 @@
   "name": "boboko/core",
   "description": "Core module — authentication and shared panel behaviour",
   "type": "library",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "autoload": {
     "psr-4": {
       "Modules\\Core\\": "src/"

database/migrations/2026_09_03_000001_add_cascade_delete_to_product_reviews_product_id.php

@@ -0,0 +1,43 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * product_reviews.product_id's original foreign key (2026_07_10_000001) had
+ * no ON DELETE clause, so deleting a Product with reviews throws a
+ * constraint violation instead of the review rows going with it — unlike
+ * every other Product-dependent table (variants, media, etc.), which does
+ * cascade. A review is dependent, disposable data, not something worth
+ * blocking a product deletion over.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->dropForeign(['product_id']);
+        });
+
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->foreign('product_id')
+                ->references('id')
+                ->on(config('lunar.database.table_prefix').'products')
+                ->cascadeOnDelete();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->dropForeign(['product_id']);
+        });
+
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->foreign('product_id')
+                ->references('id')
+                ->on(config('lunar.database.table_prefix').'products');
+        });
+    }
+};

docs/product-listing.md

@@ -135,11 +135,12 @@ needs, listing and detail alike:
 | `collections` | `$product->collections` | Array of `{id, name}` — directly assigned collections only, `name` is the translated collection name. Not filterable — see `collection_ids`. |
 | `collection_ids` | `$product->collections` + `->ancestors` | Filterable. Flat array of every directly-assigned collection's id, unioned with all of its ancestors' ids. `ProductFilters(collectionId: ...)` filters against this field, not `collections`, since products are typically attached only to leaf collections — a plain direct-match filter would never return anything for a parent/root category page. |
 | `slugs` | `$product->urls->pluck('slug')` | Filterable. Every locale's `Url::slug` for the product, so `getBySlug()` resolves purely from the index — no database read. |
+| `skus` | `$product->variants->pluck('sku')` | Filterable. Every variant's `sku`, deduplicated, empty ones dropped. Same "resolve from the index alone" reasoning as `slugs`, for a future SKU-based lookup/filter. |
 | `price` | Cheapest variant's base price | Filterable. Float in major units (e.g. `19.99`, not `1999`). Base price only — no customer group, default currency (`Currency::getDefault()`) only. `null` if the product has no priced variant yet, so it's excluded from range filters rather than treated as free. |
 | `brand` | Already indexed by Lunar's base indexer | Newly marked **filterable** — it existed in the document already, just wasn't usable in a `filter` clause. |
 | `tags` | `$product->tags->pluck('value')` | Display only. |
 | `media` | `$product->media` | Full gallery (id/url/thumb per image), not just the single thumbnail Lunar's base indexer sends. |
-| `variants` | `$product->variants` | Per variant: `id`, `sku`, `stock`, `purchasable`, `options` (option/value names, in the current locale), `prices` (per currency/customer group), `media` (variant-specific images). |
+| `variants` | `$product->variants` | Per variant: `id`, `sku`, `gtin`, `mpn`, `ean`, `stock`, `backorder`, `unit_quantity`, `purchasable`, `shippable`, `tax_ref`, `dimensions` (`length`/`width`/`height`/`weight`/`volume`, each `{value, unit}`), `options` (option/value names, in the current locale), `prices` (per currency/customer group), `media` (the variant's own images — `ProductVariant::images()`, a separate pivot from the product's own gallery above, populated by `ShopifyExportImporter` from Shopify's `Variant Image` CSV column). |
 | `reviews` | `Modules\Core\Review\Models\ProductReview` | `{items, count, average_rating}` — see "Reviews" below. |
 | `in_stock` | `$model->variants` | Filterable boolean. `true` if ANY variant currently passes `ProductVariant::canBeFulfilledAtQuantity(1)` — Lunar's own purchasability rule (`purchasable === 'always'` ignores stock entirely; `in_stock` checks `stock` alone; anything else checks `stock + backorder`). Only as fresh as the last reindex — see "Stock goes stale" below. |
 

docs/shopify-import.md

@@ -2,6 +2,9 @@
 
 Findings from comparing a real Shopify product export CSV against Lunar's schema (`vendor/lunarphp/core`), plus the resulting implementation plan for `MigrateImport\Shopify\ShopifyExportImporter`.
 
+Need to discard everything and re-import from scratch (e.g. after a schema/indexer change that
+only applies to newly-created rows)? See `docs/shopify-reimport.md`.
+
 ## Idempotency problem
 
 Nothing in Lunar tracks "this record came from external system X, ID Y." Re-running an import with no external-ID tracking would duplicate every product on each run.

docs/shopify-reimport.md

@@ -0,0 +1,149 @@
+# Wiping products before a clean Shopify re-import
+
+A runbook for discarding every imported product (and everything that hangs off one —
+variants, prices, media, reviews, options/values, the Meilisearch documents) and re-running
+`ShopifyExportImporter` from scratch. Useful after a schema/indexer change that only applies to
+newly-created rows (see "Why a wipe, not an update" below), or when the export CSV itself changed
+enough that stale products need to go, not just be updated in place.
+
+Every command below is a `tinker --execute=` one-liner run inside the app container — adjust the
+exec prefix (`./bin/dc-core.sh exec app ...`, `docker compose exec app ...`, etc.) for your setup.
+
+---
+
+## Why a wipe, not an update
+
+`ShopifyExportImporter`'s resolvers are mostly `firstOrCreate` — re-running the importer against
+an *existing* database updates matched rows but leaves already-created ones exactly as they were.
+That's the right behavior for routine re-imports (an updated price, a new variant), but it means a
+change to what gets set **at creation time only** — e.g. `ProductOptionResolver` now also setting
+`label`, not just `name`, on a `ProductOption` — never reaches a `ProductOption` row that already
+exists. A wipe forces every row to go through creation again, picking up such fixes.
+
+---
+
+## 1. Delete every product
+
+Cascades to `ProductVariant`, prices, and Spatie media rows — verified live (see
+`shopify-import.md`'s own history/commit log for context). Also removes each product's Meilisearch
+document automatically, via Scout's own delete hook fired on `forceDelete()` — no separate
+`scout:flush` needed.
+
+```php
+\Lunar\Models\Product::withTrashed()->get()->each->forceDelete();
+```
+
+**Let this run to completion.** Interrupting it mid-loop (e.g. Ctrl+C on the tinker session) stops
+after whichever product it was on, leaving the rest undeleted — safe to just re-run the same
+command again afterward, since already-deleted products are simply skipped.
+
+Verify:
+
+```php
+\Lunar\Models\Product::withTrashed()->count(); // 0
+```
+
+### Requires: `product_reviews.product_id` cascades on delete
+
+`product_reviews` (boboko-core's own table, not Lunar's) originally had no `ON DELETE` clause on
+its `product_id` foreign key — deleting a reviewed product threw a constraint violation instead of
+the review going with it. Fixed by
+`database/migrations/2026_09_03_000001_add_cascade_delete_to_product_reviews_product_id.php`. Make
+sure this migration has actually run (`php artisan migrate`) before step 1, or a product with
+reviews will fail to delete.
+
+---
+
+## 2. Delete product options and values
+
+Not touched by step 1 (`ProductOption`/`ProductOptionValue` aren't scoped to one product — they're
+shared across the catalog, per `ProductOptionResolver::resolveOption()`'s `shared: true`). Safe to
+delete in full once every product (and therefore every variant referencing an option value via the
+`product_option_value_product_variant` pivot) is gone — deleting values while variants still
+reference them throws the same kind of FK violation step 1 guards against.
+
+```php
+\Lunar\Models\ProductOptionValue::query()->delete();
+\Lunar\Models\ProductOption::query()->delete();
+```
+
+Verify:
+
+```php
+\Lunar\Models\ProductOption::count();      // 0
+\Lunar\Models\ProductOptionValue::count(); // 0
+```
+
+---
+
+## 3. Clear the import mappings
+
+Without this, the importer's `ImportMapping::resolve(...)` calls still find the (now-deleted)
+mappings' rows absent, so this step is really about not leaving stale mapping rows pointing at
+nothing — `ImportMapping` rows aren't foreign-keyed to the models they map (`morphTo`, no
+constraint), so leaving them wouldn't break the re-import, but a stale mapping for a product that
+no longer exists is dead weight.
+
+```php
+\Modules\Core\MigrateImport\Models\ImportMapping::where('source', 'shopify')->delete();
+```
+
+Verify:
+
+```php
+\Modules\Core\MigrateImport\Models\ImportMapping::where('source', 'shopify')->count(); // 0
+```
+
+---
+
+## 4. Re-run the importer
+
+`boboko:migrate:import` dispatches `RunMigrateImportJob` onto the queue — **not synchronous** —
+so a queue worker must actually be running (`php artisan queue:work`, or your dev queue container)
+or the job just sits queued.
+
+```bash
+php artisan boboko:migrate:import --source=shopify --type=export --file=<absolute path to the CSV>
+```
+
+The `--file` value must be an **absolute path** inside the container (e.g.
+`/var/www/html/storage/app/private/imports/shopify/products_export.csv`) when running
+non-interactively — a path relative to `storage/app/private/imports` only resolves correctly when
+the command can fall back to its interactive prompt, which isn't available in a scripted/non-TTY
+run.
+
+Watch the queue worker's own log output for `FAIL` entries (see `docs/lunar.md` or your compose
+setup for how logs are routed to `docker compose logs`) — a clean run shows every
+`Laravel\Scout\Jobs\MakeSearchable` / `Spatie\MediaLibrary\Conversions\Jobs\PerformConversionsJob`
+line ending `DONE`, never `FAIL`.
+
+---
+
+## 5. Re-sync Meilisearch and reindex
+
+```bash
+php artisan lunar:meilisearch:setup
+php artisan lunar:meilisearch:tune-product-search
+php artisan lunar:search:index "Lunar\Models\Product" --refresh
+```
+
+`--refresh` re-syncs filterable/sortable index settings *and* reindexes every document — it does
+not reset `typoTolerance`/`prefixSearch` (confirmed live: both survived a `--refresh` run
+unchanged), so `tune-product-search` only needs re-running here for completeness/if it hadn't
+already been applied, not because `--refresh` would have clobbered it.
+
+---
+
+## Verifying the result
+
+```php
+// Product count should match the CSV's actual unique `Handle` count, not
+// whatever the database held before the wipe — those aren't the same number
+// if stale/manually-added products existed alongside the CSV-sourced ones.
+\Lunar\Models\Product::count();
+
+// Spot-check that at least one variant picked up its own image (see
+// shopify-import.md's "Images" section) — 0 is only correct if the CSV
+// genuinely has no `Variant Image` values populated.
+\Lunar\Models\ProductVariant::has('images')->count();
+```

src/Catalog/Services/ProductIndexer.php

@@ -27,8 +27,14 @@ use Spatie\MediaLibrary\MediaCollections\Models\Media;
  *   - slugs (every locale's Url::slug for the product, filterable) — lets
  *     ProductService::getBySlug() resolve a product from the index directly, with
  *     no database read at all
+ *   - skus (every variant's sku, deduplicated, filterable) — same "resolve from the
+ *     index alone" reasoning as slugs, for a future SKU-based lookup/filter
  *   - price (cheapest variant, filterable) and full per-variant pricing
- *   - variants: sku, stock, purchasable, option values, prices, media
+ *   - variants: sku, gtin, mpn, ean, stock, backorder, unit_quantity, purchasable,
+ *     shippable, tax_ref, dimensions (length/width/height/weight/volume, each
+ *     {value, unit}), option values, prices, media — the variant's own images
+ *     (ProductVariant::images(), separate from the product's gallery below), not
+ *     the product's own media repeated per variant
  *   - the full media gallery (not just the single thumbnail Lunar's base indexer sends)
  *   - tags
  *   - reviews: {items: [...], count, average_rating} — items are public-safe fields
@@ -83,6 +89,7 @@ class ProductIndexer extends BaseProductIndexer
             'channel_ids',
             'in_stock',
             'recommendations.id',
+            'skus',
         ];
     }
 
@@ -126,6 +133,7 @@ class ProductIndexer extends BaseProductIndexer
             ->values()
             ->all();
         $data['slugs'] = $model->urls->pluck('slug')->unique()->values()->all();
+        $data['skus'] = $model->variants->pluck('sku')->filter()->unique()->values()->all();
         $data['tags'] = $model->tags->pluck('value')->all();
         $data['media'] = $model->media->map(fn (Media $media) => $this->mapMedia($media))->all();
         $data['variants'] = $model->variants->map(fn (ProductVariant $variant) => $this->mapVariant($variant, $currency))->all();
@@ -161,8 +169,22 @@ class ProductIndexer extends BaseProductIndexer
         return [
             'id' => $variant->id,
             'sku' => $variant->sku,
+            'gtin' => $variant->gtin,
+            'mpn' => $variant->mpn,
+            'ean' => $variant->ean,
             'stock' => $variant->stock,
+            'backorder' => $variant->backorder,
+            'unit_quantity' => $variant->unit_quantity,
             'purchasable' => $variant->purchasable,
+            'shippable' => $variant->shippable,
+            'tax_ref' => $variant->tax_ref,
+            'dimensions' => [
+                'length' => ['value' => $variant->length_value, 'unit' => $variant->length_unit],
+                'width' => ['value' => $variant->width_value, 'unit' => $variant->width_unit],
+                'height' => ['value' => $variant->height_value, 'unit' => $variant->height_unit],
+                'weight' => ['value' => $variant->weight_value, 'unit' => $variant->weight_unit],
+                'volume' => ['value' => $variant->volume_value, 'unit' => $variant->volume_unit],
+            ],
             'options' => $variant->values->map(fn ($value) => [
                 'option' => $this->translatedName($value->option->name),
                 'handle' => $value->option->handle,

src/MigrateImport/Shopify/Resolvers/ProductOptionResolver.php

@@ -16,10 +16,16 @@ class ProductOptionResolver
         // the same option instead of creating a near-duplicate.
         $handle = Str::slug($name) ?: 'option';
 
+        // 'label' must be set even though nothing here reads it back — a null
+        // label crashes Lunar's own ProductOptionIndexer::toSearchableArray()
+        // (foreach (null as ...)) the moment this option gets reindexed, since
+        // it assumes every ProductOption always has one. Same value as 'name'
+        // is a reasonable default; Shopify's CSV has no separate "label" concept.
         return ProductOption::query()->firstOrCreate(
             ['handle' => $handle],
             [
                 'name' => [DefaultLocale::code() => $name],
+                'label' => [DefaultLocale::code() => $name],
                 'shared' => true,
             ],
         );

src/MigrateImport/Shopify/ShopifyExportImporter.php

@@ -25,6 +25,7 @@ use Modules\Core\MigrateImport\Shopify\Resolvers\ProductOptionResolver;
 use Modules\Core\MigrateImport\Shopify\Resolvers\ProductTypeResolver;
 use Modules\Core\MigrateImport\Shopify\Resolvers\TagResolver;
 use Modules\Core\MigrateImport\Shopify\Resolvers\TaxClassResolver;
+use Spatie\MediaLibrary\MediaCollections\Models\Media;
 
 class ShopifyExportImporter implements Importer
 {
@@ -113,7 +114,7 @@ class ShopifyExportImporter implements Importer
         $options = $this->attachOptions($product, $row);
 
         foreach ($group->variantRows as $index => $variantRow) {
-            $this->importVariant($product, $group->handle, $index, $variantRow, $taxClass, $currency, $options);
+            $this->importVariant($product, $group->handle, $index, $variantRow, $taxClass, $currency, $options, $imagesPath);
         }
 
         foreach ($group->imageRows as $index => $imageRow) {
@@ -151,6 +152,7 @@ class ShopifyExportImporter implements Importer
         TaxClass $taxClass,
         Currency $currency,
         array $options,
+        string $imagesPath,
     ): void {
         $externalId = "{$handle}#{$index}";
         $existing = ImportMapping::resolve(self::SOURCE, 'variant', $externalId);
@@ -182,6 +184,26 @@ class ShopifyExportImporter implements Importer
             : null;
 
         $this->priceResolver->resolve($variant, $currency, $price, $comparePrice);
+
+        // Shopify's own "Variant Image" column — the one image a variant picker
+        // actually swaps to when that variant is selected — distinct from the
+        // product's full gallery (imageRows below). Often the same file as one
+        // of the product's own image rows, sometimes not yet imported at all
+        // (e.g. a variant-only image never listed as its own image row) — either
+        // way resolveOrImportImage() handles both via the same Image Src dedup
+        // key, so whichever of importVariant()/importImage() runs first for a
+        // given src does the actual import.
+        $variantImageSrc = trim((string) ($row['Variant Image'] ?? ''));
+
+        if ($variantImageSrc !== '') {
+            $media = $this->resolveOrImportImage($product, $handle, $variantImageSrc, 1, $imagesPath);
+
+            if ($media) {
+                $variant->images()->syncWithoutDetaching([
+                    $media->id => ['primary' => true, 'position' => 1],
+                ]);
+            }
+        }
     }
 
     private function importImage(
@@ -191,29 +213,54 @@ class ShopifyExportImporter implements Importer
         array $row,
         string $imagesPath,
     ): void {
-        $externalId = $row['Image Src'] ?: "{$handle}#image-{$index}";
         $position = (int) ($row['Image Position'] ?? $index + 1);
 
-        if (ImportMapping::resolve(self::SOURCE, 'image', $externalId)) {
-            return;
+        $this->resolveOrImportImage($product, $handle, $row['Image Src'], $position, $imagesPath);
+    }
+
+    /**
+     * Resolves the Media already imported for $imageSrc (recorded under
+     * source_type 'image', keyed by Image Src — the same URL Shopify repeats
+     * across a product's own image rows and any variant's "Variant Image"
+     * column), importing it via AssetResolver if this is the first time this
+     * src has been seen. Shared by importImage() (product gallery) and
+     * importVariant() (variant-specific image) so the same physical file is
+     * never uploaded to Spatie MediaLibrary twice just because Shopify's flat
+     * CSV format repeats the URL on multiple rows.
+     */
+    private function resolveOrImportImage(
+        Product $product,
+        string $handle,
+        string $imageSrc,
+        int $position,
+        string $imagesPath,
+    ): ?Media {
+        $externalId = $imageSrc ?: "{$handle}#image-{$position}";
+
+        $existing = ImportMapping::resolve(self::SOURCE, 'image', $externalId);
+
+        if ($existing instanceof Media) {
+            return $existing;
         }
 
-        $localFile = $this->findLocalFile($imagesPath, $row['Image Src']);
+        $localFile = $this->findLocalFile($imagesPath, $imageSrc);
 
         if ($localFile === null) {
             Log::warning('Shopify import: image file not found', [
                 'handle' => $handle,
-                'image_src' => $row['Image Src'],
+                'image_src' => $imageSrc,
             ]);
 
-            return;
+            return null;
         }
 
         $media = $this->assetResolver->resolve($product, $localFile, $position);
 
         if ($media) {
-            ImportMapping::record(self::SOURCE, 'image', $externalId, $product);
+            ImportMapping::record(self::SOURCE, 'image', $externalId, $media);
         }
+
+        return $media;
     }
 
     private function findLocalFile(string $imagesPath, string $imageSrc): ?string