Feature: Adding Product Service to Lunar
This commit introduces a Product service to Lunar. This product service calls Meilisearch to fetch an indexed product. The indexer has been updated to also include the collection and the price of the product. A product search service has also been created to be used by the frontend's search
This commit is contained in:
@@ -1206,3 +1206,5 @@ 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`.
|
||||
- **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.
|
||||
|
||||
@@ -0,0 +1,122 @@
|
||||
# Product Listing
|
||||
|
||||
`Modules\Core\Catalog\ProductService` provides browsing/filtering of the product catalog
|
||||
(list all, filter by collection/brand/price range) for a storefront, reading directly from the
|
||||
Meilisearch index rather than the database.
|
||||
|
||||
This is separate from `Modules\Core\Search\ProductSearchService` (see `product-search.md`), which
|
||||
handles free-text query search. `ProductService` is for browsing without a search term.
|
||||
|
||||
---
|
||||
|
||||
## Why it reads from the index, not the database
|
||||
|
||||
`ProductService::list()` calls `Product::search('')->paginateRaw(...)` and returns the raw
|
||||
Meilisearch hits directly — it never calls Scout's `->get()`, which would re-hydrate Eloquent
|
||||
models from the database per result. This avoids an extra database round-trip on every listing
|
||||
request, but it means **callers only get whatever fields are in the indexed document**, not the
|
||||
full `Product` model or its relations.
|
||||
|
||||
A single-product detail view needs the full record (all attributes, media, variants, etc.) and
|
||||
should look the product up directly via `Lunar\Models\Product`, not through `ProductService`.
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
```php
|
||||
use Modules\Core\Catalog\ProductFilters;
|
||||
use Modules\Core\Catalog\ProductService;
|
||||
|
||||
$service = app(ProductService::class);
|
||||
|
||||
// List everything, paginated
|
||||
$result = $service->list(perPage: 24, page: 1);
|
||||
|
||||
// Filter by collection, brand, and/or price range
|
||||
$result = $service->list(
|
||||
filters: new ProductFilters(collectionId: 17, minPrice: 10.0, maxPrice: 50.0),
|
||||
perPage: 24,
|
||||
page: 1,
|
||||
);
|
||||
|
||||
$result['data']; // array of Meilisearch documents (plain arrays, not models)
|
||||
$result['meta']['total'];
|
||||
$result['meta']['per_page'];
|
||||
$result['meta']['current_page'];
|
||||
$result['meta']['last_page'];
|
||||
```
|
||||
|
||||
All `ProductFilters` fields are optional; only the ones set are added to the Meilisearch query.
|
||||
|
||||
---
|
||||
|
||||
## Fields this depends on: `Modules\Core\Search\ProductIndexer`
|
||||
|
||||
Lunar's own `Lunar\Search\ProductIndexer` doesn't index collection membership or a comparable
|
||||
price, and only marks `__soft_deleted`, `skus`, `status` as filterable — none of what
|
||||
`ProductFilters` needs. `Modules\Core\Search\ProductIndexer` extends it to add:
|
||||
|
||||
| Field | Source | Notes |
|
||||
|---|---|---|
|
||||
| `collections` | `$product->collections->pluck('id')` | Array of collection IDs (as strings). Filtering matches by ID, not slug — the caller resolves whichever collection it means before calling `ProductService`. |
|
||||
| `price` | Cheapest variant's base price | 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. |
|
||||
|
||||
`description` and other translated attributes are indexed as-is, including any HTML markup
|
||||
(e.g. from a Shopify `Body (HTML)` import) — **not stripped**. Any view rendering a description
|
||||
sourced from `ProductService`'s results must treat it as trusted HTML.
|
||||
|
||||
---
|
||||
|
||||
## Multi-variant products and price
|
||||
|
||||
A product's `price` is its *cheapest* variant's price ("from €19.99" style), not every variant's
|
||||
price. A price-range filter matches based on that single minimum — a product with one cheap
|
||||
variant and several expensive ones will match a low-price-range filter even though most of its
|
||||
variants don't.
|
||||
|
||||
---
|
||||
|
||||
## Registering the indexer
|
||||
|
||||
Not automatic — an app opts in via its own `config/lunar/search.php`:
|
||||
|
||||
```php
|
||||
'indexers' => [
|
||||
Lunar\Models\Product::class => Modules\Core\Search\ProductIndexer::class,
|
||||
// ...other model indexers unchanged
|
||||
],
|
||||
```
|
||||
|
||||
## Re-syncing after this change
|
||||
|
||||
Filterable attributes are Meilisearch index settings, not computed per-query — changing them
|
||||
requires re-syncing settings and reindexing existing documents:
|
||||
|
||||
```bash
|
||||
php artisan lunar:meilisearch:setup
|
||||
php artisan lunar:search:index "Lunar\Models\Product" --refresh
|
||||
```
|
||||
|
||||
**If `SCOUT_QUEUE=true`, restart the queue worker after deploying an indexer change.** A running
|
||||
`queue:work` process loads PHP classes once at boot and keeps that code in memory for its entire
|
||||
lifetime — it does not pick up an edited/newly-deployed indexer class. Symptoms: reindexing
|
||||
commands succeed with no errors, `Product::toSearchableArray()` returns the new fields correctly
|
||||
when called directly (e.g. via `artisan tinker`, which always boots fresh), but documents written
|
||||
via `$model->searchable()` through the live queue are still missing the new fields. Restarting the
|
||||
queue worker (`docker compose restart queue`, or equivalent) resolves it — no code change needed.
|
||||
|
||||
---
|
||||
|
||||
## Meilisearch driver quirk: `paginateRaw()`'s `items()` is not a list of hits
|
||||
|
||||
For the Meilisearch engine specifically, Scout's `Builder::paginateRaw()` puts the **entire raw
|
||||
response** (`hits`, `query`, `processingTimeMs`, `hitsPerPage`, `page`, `totalPages`, `totalHits`)
|
||||
into the paginator's `items()`, not a plain array of documents. Calling `$paginator->items()`
|
||||
and treating it as a list (e.g. `collect($paginator->items())->values()`) silently produces a
|
||||
7-element array whose first element happens to be the real hits and the rest are stray scalars
|
||||
from the other response keys — no error, just wrong data leaking into what looks like a normal
|
||||
list. `ProductService::list()` pulls `$paginator->items()['hits']` explicitly to avoid this;
|
||||
`$paginator->total()`/`perPage()`/`currentPage()`/`lastPage()` are unaffected and safe to use
|
||||
as-is.
|
||||
@@ -0,0 +1,81 @@
|
||||
# Product Search
|
||||
|
||||
`Modules\Core\Search\ProductSearchService` provides locale-aware full-text product search on
|
||||
top of Laravel Scout + Meilisearch.
|
||||
|
||||
---
|
||||
|
||||
## Why locale-aware search isn't a filter
|
||||
|
||||
Lunar's Meilisearch indexer (`Lunar\Search\ScoutIndexer::mapSearchableAttributes()`) flattens
|
||||
every translated attribute into **locale-suffixed fields on a single document** — a product with
|
||||
a translated `name` produces `name_en`, `name_el`, etc. as separate top-level fields, not
|
||||
separate documents per locale and not a filterable `locale` field.
|
||||
|
||||
That means "search in Greek" isn't a `->filter('locale = el')` — Meilisearch has no such field to
|
||||
filter on. It's a choice of **which fields the query targets**: `name_el`/`description_el`
|
||||
instead of `name_en`/`description_en`. This is what Meilisearch's `attributesToSearchOn` search
|
||||
parameter controls, exposed through Scout via `Builder::options()`, which passes straight through
|
||||
to the underlying Meilisearch client call (`Laravel\Scout\Engines\MeilisearchEngine::performSearch()`
|
||||
merges `$builder->options` directly into the search request).
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
```php
|
||||
use Modules\Core\Search\ProductSearchService;
|
||||
|
||||
$results = app(ProductSearchService::class)->search('running shoes');
|
||||
// or an explicit locale, bypassing App::getLocale():
|
||||
$results = app(ProductSearchService::class)->search('running shoes', 'el');
|
||||
```
|
||||
|
||||
Returns an `Illuminate\Database\Eloquent\Collection` of `Lunar\Models\Product` — Scout's
|
||||
`->get()` hydrates real models from the database after the Meilisearch query, so relations
|
||||
(`variants`, `brand`, `media`, etc.) are available on the results as normal.
|
||||
|
||||
`$locale` defaults to `App::getLocale()` — already set correctly on every storefront request by
|
||||
`Modules\Core\Localization\LocaleMiddleware` (see `localization.md`), so callers in controllers
|
||||
don't need to pass it explicitly.
|
||||
|
||||
---
|
||||
|
||||
## Missing-translation fallback
|
||||
|
||||
If a product was only ever given an English name, `name_el` doesn't exist on that document at
|
||||
all (Lunar's indexer only writes a `{handle}_{locale}` field for locales actually present in the
|
||||
attribute's stored data — see `ScoutIndexer::mapSearchableAttributes()`). Searching strictly
|
||||
against `name_el` would make that product invisible to Greek-locale search, even though it's a
|
||||
real catalog item.
|
||||
|
||||
To avoid silently hiding incompletely-translated products, `ProductSearchService` targets **both**
|
||||
the resolved locale's fields **and** the default language's fields
|
||||
(`Lunar\Models\Language::getDefault()->code`) — e.g. searching in `el` targets `name_el`,
|
||||
`name_en`, `description_el`, `description_en` together (assuming `en` is the default language).
|
||||
A product missing an `el` translation still matches via its `en` fields.
|
||||
|
||||
---
|
||||
|
||||
## Field list is dynamic, not hardcoded
|
||||
|
||||
The set of attribute handles searched (`name`, `description`, or whatever else) comes from
|
||||
`Lunar\Facades\AttributeManifest::getSearchableAttributes(Product::morphName())` — the same
|
||||
source `ScoutIndexer` itself uses to decide what gets indexed. If an admin marks a new attribute
|
||||
searchable in the panel, `ProductSearchService` picks it up automatically; nothing in this class
|
||||
needs to change.
|
||||
|
||||
---
|
||||
|
||||
## Re-syncing after indexer changes
|
||||
|
||||
Changing which attributes are searchable, or `ProductIndexer`'s filterable/sortable fields,
|
||||
requires re-syncing Meilisearch's index settings and re-indexing existing documents:
|
||||
|
||||
```bash
|
||||
php artisan lunar:meilisearch:setup
|
||||
php artisan lunar:search:index "Lunar\Models\Product" --refresh
|
||||
```
|
||||
|
||||
`ProductSearchService` itself needs no re-sync when locales change — `attributesToSearchOn` is
|
||||
computed per-query from the live language list, not baked into index settings.
|
||||
@@ -0,0 +1,20 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Core\Catalog;
|
||||
|
||||
/**
|
||||
* Filter input for ProductService::list(). All fields are optional — omitted
|
||||
* filters are simply not added to the Meilisearch query. Values are matched
|
||||
* against Modules\Core\Search\ProductIndexer's document fields, so filtering
|
||||
* only works on stores where that indexer is registered and the index has
|
||||
* been re-synced (see docs/product-listing.md).
|
||||
*/
|
||||
class ProductFilters
|
||||
{
|
||||
public function __construct(
|
||||
public readonly ?int $collectionId = null,
|
||||
public readonly ?string $brand = null,
|
||||
public readonly ?float $minPrice = null,
|
||||
public readonly ?float $maxPrice = null,
|
||||
) {}
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Core\Catalog;
|
||||
|
||||
use Illuminate\Support\Collection;
|
||||
use Lunar\Models\Product;
|
||||
|
||||
/**
|
||||
* Storefront product listing/filtering, reading directly from the Meilisearch index
|
||||
* (Modules\Core\Search\ProductIndexer) rather than the database — no ->get() model
|
||||
* hydration, so callers get plain arrays of the indexed document, not Eloquent models.
|
||||
* Consumers needing the full record (e.g. a product detail page) should look the
|
||||
* product up directly via Lunar's Product model instead.
|
||||
*
|
||||
* Full-text query search lives separately in Modules\Core\Search\ProductSearchService;
|
||||
* this service is for browsing/filtering without a search term.
|
||||
*/
|
||||
class ProductService
|
||||
{
|
||||
/**
|
||||
* @return array{data: array<int, array>, meta: array}
|
||||
*/
|
||||
public function list(?ProductFilters $filters = null, int $perPage = 24, int $page = 1): array
|
||||
{
|
||||
$paginator = Product::search('')
|
||||
->options([
|
||||
'filter' => $this->buildFilter($filters),
|
||||
])
|
||||
->paginateRaw(perPage: $perPage, page: $page);
|
||||
|
||||
// For the Meilisearch driver, Scout's paginateRaw() puts the whole raw
|
||||
// response (hits, query, processingTimeMs, ...) in items(), not a plain
|
||||
// list of hits — the actual documents are under the 'hits' key.
|
||||
$rawResponse = $paginator->items();
|
||||
|
||||
return [
|
||||
'data' => collect($rawResponse['hits'] ?? [])->values()->all(),
|
||||
'meta' => [
|
||||
'total' => $paginator->total(),
|
||||
'per_page' => $paginator->perPage(),
|
||||
'current_page' => $paginator->currentPage(),
|
||||
'last_page' => $paginator->lastPage(),
|
||||
],
|
||||
];
|
||||
}
|
||||
|
||||
private function buildFilter(?ProductFilters $filters): ?string
|
||||
{
|
||||
if ($filters === null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$clauses = Collection::make([
|
||||
$filters->collectionId !== null ? "collections = \"{$filters->collectionId}\"" : null,
|
||||
$filters->brand !== null ? 'brand = "'.addcslashes($filters->brand, '"\\').'"' : null,
|
||||
$filters->minPrice !== null ? "price >= {$filters->minPrice}" : null,
|
||||
$filters->maxPrice !== null ? "price <= {$filters->maxPrice}" : null,
|
||||
])->filter();
|
||||
|
||||
return $clauses->isEmpty() ? null : $clauses->join(' AND ');
|
||||
}
|
||||
}
|
||||
@@ -2,26 +2,62 @@
|
||||
|
||||
namespace Modules\Core\Search;
|
||||
|
||||
use Illuminate\Database\Eloquent\Builder;
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
use Lunar\Models\Currency;
|
||||
use Lunar\Models\Product;
|
||||
use Lunar\Search\ProductIndexer as BaseProductIndexer;
|
||||
|
||||
/**
|
||||
* Lunar's own indexer puts raw attribute HTML (e.g. name_en, description_en) into
|
||||
* the search index, which pollutes relevance ranking and highlighting with markup.
|
||||
* Strip tags from string fields before they reach Meilisearch.
|
||||
* Extends Lunar's own indexer to add fields needed for storefront listing/filtering
|
||||
* (Modules\Core\Catalog\ProductService) that aren't part of Lunar's default document:
|
||||
* collection membership and a comparable price. Neither is filterable in Meilisearch
|
||||
* until `php artisan lunar:meilisearch:setup` re-syncs index settings and the index is
|
||||
* refreshed — see docs/product-listing.md.
|
||||
*/
|
||||
class ProductIndexer extends BaseProductIndexer
|
||||
{
|
||||
public function getFilterableFields(): array
|
||||
{
|
||||
return [
|
||||
...parent::getFilterableFields(),
|
||||
'brand',
|
||||
'collections',
|
||||
'price',
|
||||
];
|
||||
}
|
||||
|
||||
public function makeAllSearchableUsing(Builder $query): Builder
|
||||
{
|
||||
return parent::makeAllSearchableUsing($query)->with(['collections', 'variants.prices']);
|
||||
}
|
||||
|
||||
public function toSearchableArray(Model $model): array
|
||||
{
|
||||
/** @var Product $model */
|
||||
$data = parent::toSearchableArray($model);
|
||||
|
||||
foreach ($data as $key => $value) {
|
||||
if (is_string($value)) {
|
||||
$data[$key] = trim(strip_tags($value));
|
||||
}
|
||||
}
|
||||
$data['collections'] = $model->collections->pluck('id')->map(fn ($id) => (string) $id)->all();
|
||||
$data['price'] = $this->cheapestPrice($model);
|
||||
|
||||
return $data;
|
||||
}
|
||||
|
||||
/**
|
||||
* The cheapest variant's base price (no customer group) in the default currency,
|
||||
* as a float in major units — e.g. 19.99, not 1999. Null if the product has no
|
||||
* variant with a price in that currency yet, so it's excluded from price filters
|
||||
* rather than sorting to the bottom as if it were free.
|
||||
*/
|
||||
private function cheapestPrice(Product $model): ?float
|
||||
{
|
||||
$currency = Currency::getDefault();
|
||||
|
||||
$price = $model->variants
|
||||
->flatMap(fn ($variant) => $variant->prices)
|
||||
->filter(fn ($price) => $price->currency_id === $currency->id && $price->customer_group_id === null)
|
||||
->min(fn ($price) => $price->price->value);
|
||||
|
||||
return $price !== null ? $price / (10 ** $currency->decimal_places) : null;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Core\Search;
|
||||
|
||||
use Illuminate\Database\Eloquent\Collection;
|
||||
use Illuminate\Support\Facades\App;
|
||||
use Lunar\Facades\AttributeManifest;
|
||||
use Lunar\Models\Language;
|
||||
use Lunar\Models\Product;
|
||||
|
||||
/**
|
||||
* Lunar's Meilisearch indexer flattens translated attributes into locale-suffixed
|
||||
* fields on a single document (name_en, name_el, description_en, description_el —
|
||||
* see Lunar\Search\ScoutIndexer::mapSearchableAttributes()), not separate indexes
|
||||
* or a filterable locale field. Locale-aware search means choosing which fields
|
||||
* to search on, not filtering results by locale.
|
||||
*/
|
||||
class ProductSearchService
|
||||
{
|
||||
/**
|
||||
* @return Collection<int, Product>
|
||||
*/
|
||||
public function search(string $query, ?string $locale = null): Collection
|
||||
{
|
||||
$locale ??= App::getLocale();
|
||||
$defaultLocale = Language::getDefault()->code;
|
||||
|
||||
return Product::search($query)
|
||||
->options([
|
||||
'attributesToSearchOn' => $this->searchableFields($locale, $defaultLocale),
|
||||
])
|
||||
->get();
|
||||
}
|
||||
|
||||
/**
|
||||
* Target the resolved locale's fields plus the default locale's fields, so a
|
||||
* product that's only ever been translated into the default language still
|
||||
* surfaces when searched in another locale, instead of becoming invisible
|
||||
* until every product is fully translated.
|
||||
*
|
||||
* @return array<int, string>
|
||||
*/
|
||||
private function searchableFields(string $locale, string $defaultLocale): array
|
||||
{
|
||||
$handles = AttributeManifest::getSearchableAttributes(Product::morphName())
|
||||
->pluck('handle');
|
||||
|
||||
$locales = array_unique([$locale, $defaultLocale]);
|
||||
|
||||
return $handles
|
||||
->crossJoin($locales)
|
||||
->map(fn (array $pair) => "{$pair[0]}_{$pair[1]}")
|
||||
->values()
|
||||
->all();
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user