Catalog, Products & Variants
- Introduction
- Relational Schema Architecture
- Dynamic Variant Matrices (PostgreSQL JSONB)
- Managing Products & Variants via Eloquent
- Category Trees & Hierarchies
- Persian Slugging & SEO Metadata
Introduction
The catalog engine in Reyhan Commerce provides a high-performance relational structure capable of handling simple goods, multi-attribute configurable products (e.g., color, size, volume), dynamic pricing matrices, and localized media galleries.
Instead of adopting slow EAV (Entity-Attribute-Value) anti-patterns with dozen-table SQL joins, Reyhan leverages PostgreSQL 17 JSONB with GIN indexing for blazing-fast attribute filtering and variant lookup.
Relational Schema Architecture
Dynamic Variant Matrices (PostgreSQL JSONB)
Product variants store their specific attributes in an indexed attribute_values JSONB column:
{
"color": {
"name": "قرمز یاقوتی",
"hex": "#E11D48"
},
"volume": {
"name": "۵۰ میلیلیتر",
"unit": "ml",
"value": 50
}
}Key Advantages
- Zero Database Migrations for New Attributes: Store owners can dynamically define new attributes (e.g., Shade, Finish, Fabric, Size) from the Filament admin panel without altering database tables.
- Sub-Millisecond Querying: GIN-indexed querying enables instant faceted search in PostgreSQL:sql
SELECT * FROM product_variants WHERE attribute_values->'color'->>'hex' = '#E11D48';
Managing Products & Variants via Eloquent
You can query products and eager-load variants fluently:
use Reyhan\Core\Models\Product;
// Query active products with available variants
$products = Product::query()
->where('is_active', true)
->with(['variants' => fn ($q) => $q->where('stock', '>', 0)])
->paginate(24);Accessing Variant Attributes
$variant = $product->variants->first();
// Access strongly typed attribute values
$colorName = $variant->attribute_values['color']['name'] ?? null;Category Trees & Hierarchies
Reyhan features nested tree categories powered by alareqi/filament-tree:
use Reyhan\Core\Models\Category;
// Retrieve root categories with descendants
$categoryTree = Category::query()
->whereNull('parent_id')
->with('children.children')
->get();Persian Slugging & SEO Metadata
Reyhan includes automated Persian-compatible unique slug generation and OpenGraph metadata generation:
- Automatically cleans irregular Persian characters and whitespace.
- Generates SEO Schema.org
Productstructured data JSON-LD out of the box for search engine indexing.