Download the PHP package aliziodev/laravel-product-catalog without Composer

A professional, variant-centric product catalog package for Laravel 12+. Designed to be a stable foundation for any application that needs structured product data — from a simple internal catalog to a full ecommerce storefront — without locking you into a specific architecture.

Table of Contents

• Suitable For
• Features
• Installation
• Configuration
• Basic Usage
  • Products
  • Variants & Options
  • Inventory
  • Taxonomy
  • Querying
• Product Specifications
• Slug Routing
• API Resources
• Events
• Inventory Policies
• Spatie Media Library Integration
• Custom Inventory Driver
• Use-Case Docs

Suitable For

Features

Catalog

• Products with lifecycle status: draft → published → archived
• Product code (code) as the parent SKU; per-variant SKUs for child variants
• Permanent slug routing — URLs stay valid even when the product name changes
• ProductSearchBuilder — fluent catalog-aware search with filters for category, brand, tags, price range, and stock status
• fromRequest() — map HTTP query-string params to the builder in one line
• Text search via LIKE (zero config) or MySQL FULLTEXT (opt-in via search.fulltext = true)
• Scout integration — plug in Algolia, Meilisearch, or Typesense via ScoutSearchDriver
• Taxonomy: Brand, Category (parent–child hierarchy), Tag — all with soft delete

Variants & Options

• ProductVariant as the primary sellable unit, not Product
• String-based options (Color, Size, etc.) with no separate master table required
• Auto-generated label from combined option values: "Red / XL"
• Auto-generate SKU from product code + option values
• Sale price, compare price (discount), and cost price per variant
• Physical dimensions (weight, length, width, height) for shipping calculation
• meta JSON for custom attributes without additional migrations

Inventory

• Three policies per variant: track (deduct stock), allow (always available), deny (unavailable)
• Soft-reserve (reserved_quantity) to hold stock while awaiting payment
• Full reservation lifecycle via the driver: reserve() → release() / commit()
• Low-stock threshold and alerts
• Append-only movement history (audit trail for every stock change, including reservations)
• MovementType enum: Restock, Deduction, Adjustment, Set, Reserve, Release
• InventoryReason constants for consistent audit trail reason strings
• Driver pattern — swap the stock system without changing application code
• Built-in: database (stock in DB) and null (always in stock, for digital products)

Extensibility

• Custom inventory driver — integrate your own stock system via a single interface
• No forced image schema — integrate spatie/laravel-medialibrary or any media solution you prefer
• Events: ProductPublished, ProductArchived, InventoryAdjusted
• Configurable table prefix — safe to install alongside any existing schema

Why This Package

Most ecommerce packages bundle payment, cart, and order management alongside the catalog. This package does one thing well: product catalog with variant-centric inventory. You own the order flow.

• Product is a presentation entity. ProductVariant is the sellable unit.
• Inventory is pluggable — connect your own stock system via a single interface without touching your existing code.
• No forced image schema — integrate spatie/laravel-medialibrary or your own solution.
• Configurable table prefix — safe to install alongside any existing schema.
• Slug routing that survives product renames (Shopee-style permanent route key).

Requirements

• PHP ^8.3
• Laravel ^12.0 | ^13.0

Quick Start

Installation

Publish and run the migrations:

Optionally publish the config:

Or run the interactive installer:

Configuration

Basic Usage

Products

Variants & Options

Inventory

Reservation Lifecycle

Use the inventory driver for reserve/release/commit — these methods record movements and fire events.

InventoryReason

Use InventoryReason constants to keep reason strings consistent across your application.

Add your own reason strings to config/product-catalog.php:

Taxonomy

Querying

Product Specifications

Both Product and ProductVariant have a meta JSON column for storing arbitrary key-value data — including product specifications.

Why there is no dedicated product_attributes table in this package

A filterable attribute system is a common need — but not a universal one:

Because attribute schemas differ across domains, a single built-in implementation would either be too opinionated (forcing a schema that doesn't fit your domain) or too generic (adding migration weight for every consumer, even those that don't need it). The meta JSON column is the right default for specs that are display-only.

When to add filterable attributes at the application level

If your application needs to filter or search products by specification value, add a product_attributes table in your own migration:

Extend the Product model in your application:

Filter by attribute:

This keeps the package lean and gives your application full control over the attribute schema, indexing strategy, and query patterns.

Search

The default driver is database (Eloquent LIKE, no extra dependencies). Switch to scout driver for Meilisearch, Algolia, or Typesense — see docs/scout-integration.md.

When using scout, set the top-level model key to your application Product model that extends the package base model and uses both Laravel\Scout\Searchable and Aliziodev\ProductCatalog\Concerns\Searchable. This same key is read by the database search driver and the API controller — configure your extended model once, everywhere.

Slug Routing

Slugs use a permanent random route_key suffix (Shopee-style). Renaming a product regenerates the slug prefix but keeps the same route key, so old URLs still resolve.

Enable the built-in read-only API routes:

API Resources

Response shape:

Events

Inventory Policies

Set per InventoryItem via policy column:

Spatie Media Library Integration

This package intentionally excludes a built-in image gallery to stay compatible with any media solution your application already uses.

Install spatie/laravel-medialibrary:

Extend the Product model in your application:

Important: Laravel's service container bind() does not affect Eloquent relationships. The package's $variant->product() is hardcoded to BaseProduct::class and will still return the base model. Choose one of the two approaches below.

Approach A — Simple (recommended for most projects)

Use App\Models\Product in all your app code. When you get a product through a variant relationship and need media, re-query with your model:

Approach B — Override the relationship (complete solution)

Also extend ProductVariant to return your Product:

Then use App\Models\ProductVariant everywhere in your app code.

Upload and retrieve:

Custom Inventory Driver

If your application already has its own stock system — your own inventories table, an ERP, or a third-party WMS — you don't have to use the package's catalog_inventory_items table. Implement InventoryProviderInterface and the package will talk to your system instead.

Register the driver in a ServiceProvider:

Activate via .env:

For more examples (ERP/WMS API, fallback strategy) see docs/custom-inventory-provider.md.

Testing

When writing tests for code that uses this package, set up your test case with migrations and factories:

For tests that need the inventory facade, swap to the null driver so no DB records are required:

To override the inventory driver in a specific test:

Use-Case Docs

Detailed guides for specific scenarios:

License

MIT — see LICENSE.