core/docs/collections.md

Collections

Modules\Core\Catalog\Services\CollectionService provides category browsing/nav AND single-collection lookup for a storefront — list(), getById(), getBySlug() — all reading directly from the Meilisearch index, mirroring Modules\Core\Catalog\Services\ProductService (see product-listing.md) exactly.

---

Why it reads from the index, not the database

Lunar's own Lunar\Search\CollectionIndexer only carries id/name/created_at — nowhere near enough for a storefront category page or a nav tree. Modules\Core\Catalog\Services\CollectionIndexer extends it to add everything CollectionService needs:

Field	Source	Notes
parent_id	$model->parent_id	Filterable. The nested-set tree's parent pointer — null for a top-level collection.
_lft	$model->_lft	Filterable and sortable. The nested-set tree position — lets CollectionService resolve tree order without a database read.
collection_group_id	$model->collection_group_id	Filterable. Mirrors Collection::scopeInGroup().
slugs	$model->urls->pluck('slug')	Filterable. Every locale's Url::slug, so getBySlug() resolves purely from the index.
thumbnail	$model->getThumbnailImage()	Display only. null if the collection has no thumbnail image.
ancestors	$model->ancestors	Display only. Array of {id, name}, ordered root-first — a breadcrumb (Home > Apparel > Keychains) can render directly from a single getById()/getBySlug() call, no extra queries. Empty array for a top-level collection.
product_count	Queried from the product Meilisearch index at collection-index time	Display only. How many products are in this collection or any of its descendants — matches what ProductService::list(ProductFilters(collectionId: ...)) would return, not just direct assignment. Computed via Product::search('')->options(['filter' => "collection_ids = \"{id}\""]), so it depends on the product index already being current — reindex products before collections (see "Gotchas" below).

name/description (and any other TranslatedText attribute) are indexed per-locale by Lunar's base indexer and resolved by CollectionService exactly like ProductService does — see product-listing.md's "Locale resolution" section, same logic, same LanguageCache::defaultLocale() fallback.

---

Usage

use Modules\Core\Catalog\DTOs\CollectionFilters;
use Modules\Core\Catalog\Enums\CollectionSort;
use Modules\Core\Catalog\Services\CollectionService;

$service = app(CollectionService::class);

// Top-level collections only (parent_id IS NULL) — for building a nav tree
$roots = $service->list(
    filters: new CollectionFilters(rootOnly: true),
    sort: CollectionSort::Position,
);

// Children of a specific collection
$children = $service->list(
    filters: new CollectionFilters(parentId: 222),
    sort: CollectionSort::Position,
);

// Filter by collection group
$collections = $service->list(filters: new CollectionFilters(groupId: 4));

// Single collection, by primary key or slug
$collection = $service->getById(223);
$collection = $service->getBySlug('keychains');

CollectionFilters(parentId: ..., rootOnly: ...) are mutually exclusive — if both are set, parentId wins. There's no parentId: null shorthand for "root only", since that would be ambiguous with "don't filter by parent at all" (the DTO's actual default); rootOnly names the root-collections case explicitly instead.

CollectionSort::Position (_lft:asc) is the recommended default for any nav/tree UI — it matches the order an admin arranges collections in Lunar's own Filament UI. Name and Newest are also available, mirroring ProductSort's shape.

---

Registration

Like ProductIndexer, CollectionIndexer must be registered in the consuming app's own config/lunar/search.php:

'indexers' => [
    Lunar\Models\Collection::class => Modules\Core\Catalog\Services\CollectionIndexer::class,
    // ...
],

New/changed fields aren't filterable/sortable in Meilisearch until php artisan lunar:meilisearch:setup re-syncs index settings, and existing documents need lunar:search:index --refresh to pick up the new shape. If SCOUT_QUEUE is enabled, the queue worker also needs restarting after deploying changes to the indexer class — see docs/lunar.md "Gotchas".

product_count needs the product index reindexed first. config/lunar/search.php's indexers array is typically ordered Collection before Product, so a plain lunar:search:index --refresh computes product_count against whatever the product index held before this run — stale if products changed too. lunar:search:index takes an explicit model list as its argument (--ignore restricts it to only those), so reindex products first, then collections, when both need a fresh --refresh in the same deploy:

php artisan lunar:search:index "Lunar\Models\Product" --ignore --refresh
php artisan lunar:search:index "Lunar\Models\Collection" --ignore --refresh

---

When to still use Eloquent directly

A single collection's full detail page (breadcrumb via $collection->breadcrumb, tree ancestors/descendants, route-model-bound Collection $collection in a controller signature) should keep reading Eloquent directly rather than going through CollectionService — the indexed document doesn't carry ancestor chains or the full nested-set relations, and route-model binding already gives a controller the full model for free. CollectionService is for browsing/listing and lightweight by-id/by-slug lookups where a full Eloquent hydration would be wasteful, the same tradeoff ProductService makes for products.