From ef356a639701cb1e940e1857232c7790def8a5e7 Mon Sep 17 00:00:00 2001 From: Konstantinos Arvanitakis Date: Thu, 27 Aug 2026 01:05:04 +0300 Subject: [PATCH] Feature: Products Restructuring to follow a strict rule --- docs/lunar.md | 4 ++-- docs/product-listing.md | 22 +++++++++---------- docs/product-search.md | 4 ++-- src/Localization/Services/LanguageCache.php | 4 ++-- .../DTOs}/ProductFilters.php | 8 +++---- .../Enums}/ProductSort.php | 9 ++++---- .../Services}/ProductIndexer.php | 8 +++---- .../Services}/ProductSearchService.php | 2 +- .../Services}/ProductService.php | 18 ++++++++------- src/Providers/ReviewServiceProvider.php | 4 ++-- src/Review/Models/ProductReview.php | 4 ++-- 11 files changed, 45 insertions(+), 42 deletions(-) rename src/{Catalog => Product/DTOs}/ProductFilters.php (63%) rename src/{Catalog => Product/Enums}/ProductSort.php (59%) rename src/{Search => Product/Services}/ProductIndexer.php (96%) rename src/{Search => Product/Services}/ProductSearchService.php (97%) rename src/{Catalog => Product/Services}/ProductService.php (89%) diff --git a/docs/lunar.md b/docs/lunar.md index 9e97e70..24a84ec 100644 --- a/docs/lunar.md +++ b/docs/lunar.md @@ -1206,6 +1206,6 @@ Real bugs/traps hit while building against Lunar in this package — not obvious - **`ProductOption.handle` must be unique and non-null if a product has more than one option.** Lunar's Filament variant-switcher widget does `SelectFilter::make($option->handle)` per option — two options with a `null`/matching handle throws "Filter must have a unique name" as a 500 when opening that product's variant pricing page. Always derive a slug and check uniqueness. - **`Attribute.position` is per-group, and the panel sorts by it.** Hardcoding `position => 1` for multiple new attributes in the same group makes their order undefined/collide with existing attributes at position 1. Compute `max('position') + 1` per group instead. - **Currency `decimal_places` isn't always 2.** A seeded/demo currency can have the wrong value (seen: EUR seeded with `decimal_places = 1`), which silently corrupts every price display (`€16.50` renders as `165`). If prices look wrong by a factor of 10, check the currency row before assuming the price-writing code is broken. -- **`Builder::paginateRaw()`'s `items()` is not a hit list on the Meilisearch driver.** It contains the *entire* raw response (`hits`, `query`, `processingTimeMs`, `hitsPerPage`, `page`, `totalPages`, `totalHits`) as one associative array. Treating `$paginator->items()` as a plain list (e.g. `collect($paginator->items())->values()`) silently produces 7 elements — the real hits array happens to land first, the rest are stray scalars from the other response keys — no error, just corrupted data. Pull `$paginator->items()['hits']` explicitly. `total()`/`perPage()`/`currentPage()`/`lastPage()` on the paginator are unaffected. See `Modules\Core\Catalog\ProductService` / `docs/product-listing.md`. -- **`ProductOption`/`ProductOptionValue::$name` is not `attribute_data` — `translateAttribute('name')` silently returns null for them.** Unlike `Product`/`Collection`/`Brand`, their translated `name` is a plain locale-keyed array cast (`AsArrayObject`) directly on the column, not stored in `attribute_data`. `HasTranslations::translateAttribute()` only reads `attribute_data`, so calling it on these two models compiles fine and returns `null` with no error — read the array directly instead (`$value->name[$locale] ?? ...`). See `Modules\Core\Search\ProductIndexer::translatedName()`. +- **`Builder::paginateRaw()`'s `items()` is not a hit list on the Meilisearch driver.** It contains the *entire* raw response (`hits`, `query`, `processingTimeMs`, `hitsPerPage`, `page`, `totalPages`, `totalHits`) as one associative array. Treating `$paginator->items()` as a plain list (e.g. `collect($paginator->items())->values()`) silently produces 7 elements — the real hits array happens to land first, the rest are stray scalars from the other response keys — no error, just corrupted data. Pull `$paginator->items()['hits']` explicitly. `total()`/`perPage()`/`currentPage()`/`lastPage()` on the paginator are unaffected. See `Modules\Core\Product\Services\ProductService` / `docs/product-listing.md`. +- **`ProductOption`/`ProductOptionValue::$name` is not `attribute_data` — `translateAttribute('name')` silently returns null for them.** Unlike `Product`/`Collection`/`Brand`, their translated `name` is a plain locale-keyed array cast (`AsArrayObject`) directly on the column, not stored in `attribute_data`. `HasTranslations::translateAttribute()` only reads `attribute_data`, so calling it on these two models compiles fine and returns `null` with no error — read the array directly instead (`$value->name[$locale] ?? ...`). See `Modules\Core\Product\Services\ProductIndexer::translatedName()`. - **A running `queue:work` process does not pick up an edited/newly-added Scout indexer class.** It loads PHP classes once at boot and keeps them for the process's lifetime. Symptoms: reindexing commands succeed with no errors, calling `toSearchableArray()` directly (e.g. via `artisan tinker`, which always boots fresh) returns the new fields correctly, but documents written via `$model->searchable()` through the live queue are still missing them. Restart the queue worker after deploying an indexer change — no code fix needed. diff --git a/docs/product-listing.md b/docs/product-listing.md index d52287a..8a331ed 100644 --- a/docs/product-listing.md +++ b/docs/product-listing.md @@ -1,10 +1,10 @@ # Product Listing -`Modules\Core\Catalog\ProductService` provides catalog browsing/filtering AND single-product +`Modules\Core\Product\Services\ProductService` provides catalog browsing/filtering AND single-product lookup for a storefront — `list()`, `getById()`, `getBySlug()` — all reading directly from the Meilisearch index rather than the database. One data source for everything this service does. -This is separate from `Modules\Core\Search\ProductSearchService` (see `product-search.md`), which +This is separate from `Modules\Core\Product\Services\ProductSearchService` (see `product-search.md`), which handles free-text query search. `ProductService` is for browsing/lookup without a search term. --- @@ -14,7 +14,7 @@ handles free-text query search. `ProductService` is for browsing/lookup without Every method here reads Meilisearch documents directly and returns plain arrays — never Scout's `->get()`, which would re-hydrate Eloquent models from the database. This means the index has to carry everything a detail page needs (variants, prices, options, media, reviews — see below), not -just the trimmed fields a listing page needs. `Modules\Core\Search\ProductIndexer` is built to +just the trimmed fields a listing page needs. `Modules\Core\Product\Services\ProductIndexer` is built to carry that full shape. --- @@ -22,9 +22,9 @@ carry that full shape. ## Usage ```php -use Modules\Core\Catalog\ProductFilters; -use Modules\Core\Catalog\ProductService; -use Modules\Core\Catalog\ProductSort; +use Modules\Core\Product\DTOs\ProductFilters; +use Modules\Core\Product\Services\ProductService; +use Modules\Core\Product\Enums\ProductSort; $service = app(ProductService::class); @@ -62,11 +62,11 @@ All `ProductFilters` fields are optional; only the ones set are added to the Mei --- -## Fields this depends on: `Modules\Core\Search\ProductIndexer` +## Fields this depends on: `Modules\Core\Product\Services\ProductIndexer` Lunar's own `Lunar\Search\ProductIndexer` only carries listing-grade fields (name, description, status, brand, a single thumbnail, skus) and marks just `__soft_deleted`, `skus`, `status` as -filterable. `Modules\Core\Search\ProductIndexer` extends it to add everything `ProductService` +filterable. `Modules\Core\Product\Services\ProductIndexer` extends it to add everything `ProductService` needs, listing and detail alike: | Field | Source | Notes | @@ -149,9 +149,9 @@ variants don't. ## Sorting -`ProductSort` (`Modules\Core\Catalog\ProductSort`) is a fixed enum of supported sort orders — +`ProductSort` (`Modules\Core\Product\Enums\ProductSort`) is a fixed enum of supported sort orders — `PriceAsc`, `PriceDesc`, `Newest` — each mapping to a Meilisearch `sort` clause against a field -`Modules\Core\Search\ProductIndexer::getSortableFields()` marks sortable (`price`, plus +`Modules\Core\Product\Services\ProductIndexer::getSortableFields()` marks sortable (`price`, plus `created_at`/`updated_at`/`skus`/`status` inherited from Lunar's base indexer). Adding a new `ProductSort` case requires adding the matching field to `getSortableFields()` and re-syncing (see below) — sortable attributes are index settings, not computed per-query, same as filterable ones. @@ -168,7 +168,7 @@ Not automatic — an app opts in via its own `config/lunar/search.php`: ```php 'indexers' => [ - Lunar\Models\Product::class => Modules\Core\Search\ProductIndexer::class, + Lunar\Models\Product::class => Modules\Core\Product\Services\ProductIndexer::class, // ...other model indexers unchanged ], ``` diff --git a/docs/product-search.md b/docs/product-search.md index 8f3a98b..564c5a4 100644 --- a/docs/product-search.md +++ b/docs/product-search.md @@ -1,6 +1,6 @@ # Product Search -`Modules\Core\Search\ProductSearchService` provides locale-aware full-text product search on +`Modules\Core\Product\Services\ProductSearchService` provides locale-aware full-text product search on top of Laravel Scout + Meilisearch. --- @@ -24,7 +24,7 @@ merges `$builder->options` directly into the search request). ## Usage ```php -use Modules\Core\Search\ProductSearchService; +use Modules\Core\Product\Services\ProductSearchService; $results = app(ProductSearchService::class)->search('running shoes'); // or an explicit locale, bypassing App::getLocale(): diff --git a/src/Localization/Services/LanguageCache.php b/src/Localization/Services/LanguageCache.php index 62f9b3e..1e03b60 100644 --- a/src/Localization/Services/LanguageCache.php +++ b/src/Localization/Services/LanguageCache.php @@ -9,7 +9,7 @@ use Lunar\Models\Language; /** * Cached read layer over Lunar's `languages` table — the single source both * Modules\Core\Localization\LocaleMiddleware (request-time locale resolution) and - * any other locale-aware code (e.g. Modules\Core\Catalog\ProductService) read + * any other locale-aware code (e.g. Modules\Core\Product\Services\ProductService) read * from, so the language list is fetched once per cache lifetime rather than once * per caller. Cached forever, invalidated via forget() by * Modules\Core\Localization\Listeners\FlushLanguageCache on @@ -41,7 +41,7 @@ class LanguageCache /** * Every configured store locale code (e.g. ['el', 'en']) - for code that needs * to enumerate all locales a TranslatedText attribute was indexed under (see - * Modules\Core\Catalog\ProductService::withLocalizedFields()), rather than + * Modules\Core\Product\Services\ProductService::withLocalizedFields()), rather than * hardcoding locale codes. * * @return array diff --git a/src/Catalog/ProductFilters.php b/src/Product/DTOs/ProductFilters.php similarity index 63% rename from src/Catalog/ProductFilters.php rename to src/Product/DTOs/ProductFilters.php index 5701d01..e1257d8 100644 --- a/src/Catalog/ProductFilters.php +++ b/src/Product/DTOs/ProductFilters.php @@ -1,13 +1,13 @@ get() model hydration anywhere in this service. Callers get plain arrays of the - * indexed document, not Eloquent models. + * from the Meilisearch index (Modules\Core\Product\Services\ProductIndexer) - one data + * source, no ->get() model hydration anywhere in this service. Callers get plain arrays + * of the indexed document, not Eloquent models. * - * Full-text query search lives separately in Modules\Core\Search\ProductSearchService; - * this service is for browsing/filtering without a search term. + * Full-text query search lives separately in Modules\Core\Product\Services\ + * ProductSearchService; this service is for browsing/filtering without a search term. */ class ProductService { @@ -60,8 +62,8 @@ class ProductService /** * Look up a single product by its URL slug (any locale - slugs are indexed across - * all languages, see Modules\Core\Search\ProductIndexer). Returns the full indexed - * product document, or null if no product has that slug. + * all languages, see Modules\Core\Product\Services\ProductIndexer). Returns the full + * indexed product document, or null if no product has that slug. */ public function getBySlug(string $slug): ?array { diff --git a/src/Providers/ReviewServiceProvider.php b/src/Providers/ReviewServiceProvider.php index 0651a6c..c5a32e1 100644 --- a/src/Providers/ReviewServiceProvider.php +++ b/src/Providers/ReviewServiceProvider.php @@ -9,8 +9,8 @@ use Modules\Core\Review\Models\ProductReview; * Keeps a product's Meilisearch document in sync with its reviews. A review is * created/edited independently of its product (customer submission, staff reply), * so the product's own save/update events never fire for it — without this listener, - * Modules\Core\Search\ProductIndexer's review data would only refresh on the next - * full product reindex. + * Modules\Core\Product\Services\ProductIndexer's review data would only refresh on + * the next full product reindex. */ class ReviewServiceProvider extends ServiceProvider { diff --git a/src/Review/Models/ProductReview.php b/src/Review/Models/ProductReview.php index 1b94424..d2ab244 100644 --- a/src/Review/Models/ProductReview.php +++ b/src/Review/Models/ProductReview.php @@ -38,8 +38,8 @@ class ProductReview extends Model implements HasMedia * Unlike Product/ProductVariant, this model sits outside Lunar's own * MediaDefinitionsInterface (Lunar\Base\StandardMediaDefinitions), which is * what registers the 'small' conversion those models get automatically. Without - * this, Modules\Core\Search\ProductIndexer::mapMedia() — shared across product, - * variant, and review media — throws Spatie\MediaLibrary\MediaCollections\ + * this, Modules\Core\Product\Services\ProductIndexer::mapMedia() — shared across + * product, variant, and review media — throws Spatie\MediaLibrary\MediaCollections\ * Exceptions\InvalidConversion the first time a review has an image, since * $media->getUrl('small') has no matching conversion to resolve. */