Categories
Complete reference for the Category model, hierarchical relationships, and usage in Shopper.
Categories provide a hierarchical organization structure for your products. Shopper uses nested categories with parent-child relationships, allowing unlimited depth. You can model complex product taxonomies like Electronics > Computers > Laptops without artificial limits.
Model
The model used is Shopper\Models\Category, which extends Shopper\Core\Models\Category. It implements the Shopper\Core\Models\Contracts\Category contract and Spatie\MediaLibrary\HasMedia for media support.
The core model provides the business logic (relationships, scopes, slug handling, hierarchical structure via laravel-adjacency-list) and declares its two media collections in getMediaCollections(). The admin model registers those collections with Spatie MediaLibrary and adds the image conversions through the HasMedia and RegistersMediaCollections traits. This separation means the core model has no dependency on Spatie MediaLibrary. Media support is added at the admin layer.
Extending the Model
To add custom behavior, extend the admin model and update your configuration:
namespace App\Models;
use Shopper\Models\Category as ShopperCategory;
class Category extends ShopperCategory
{
}Update config/shopper/models.php:
return [
'category' => \App\Models\Category::class,
];Database Schema
Categories are stored in the sh_categories table (sh_ is the default table prefix).
| Column | Type | Nullable | Default | Description |
|---|---|---|---|---|
id | bigint | no | auto | Primary key |
name | string | no | - | Category name |
slug | string | yes | null | URL-friendly identifier (unique) |
description | longtext | yes | null | Category description |
position | smallint (unsigned) | no | 0 | Display order among siblings (set by the admin reorder panel) |
is_enabled | boolean | no | false | Category visibility status |
seo_title | string(60) | yes | null | SEO meta title |
seo_description | string(160) | yes | null | SEO meta description |
metadata | jsonb | yes | null | Additional custom data |
parent_id | bigint (unsigned) | yes | null | Foreign key to the parent category. Set to null when the parent is deleted, so its children become root categories |
created_at | timestamp | yes | null | Creation timestamp |
updated_at | timestamp | yes | null | Last update timestamp |
The HasSlug trait runs any slug you set through Str::slug() and appends -1, -2, etc. if the slug is already taken. It does not build the slug from the name. The admin category form fills the slug from the name for you, and the CategoryObserver sets it for subcategories (see Custom Paths & Slug Behavior). When you create a root category in code, pass a slug yourself, otherwise the column stays null.
Hierarchical Structure
Categories support unlimited nesting levels, so you can organize products into deeply nested taxonomies:
Electronics (parent_id: null)
├── Computers (parent_id: 1)
│ ├── Laptops (parent_id: 2)
│ └── Desktops (parent_id: 2)
├── Phones (parent_id: 1)
│ ├── Smartphones (parent_id: 5)
│ └── Accessories (parent_id: 5)
└── Audio (parent_id: 1)Media
Categories support two media collections through Spatie MediaLibrary, using the same config-driven collection names as products.
| Collection | Config key | Behavior | Description |
|---|---|---|---|
| Default gallery | shopper.media.storage.collection_name | Multiple files | Category images |
| Thumbnail | shopper.media.storage.thumbnail_collection | Single file | Primary image for listings and navigation |
Both collections accept the MIME types listed in shopper.media.accepts_mime_types: JPEG, PNG, WebP and AVIF by default (configurable in config/shopper/media.php). The admin category form uploads a single image to the thumbnail collection, limited to shopper.media.max_size.thumbnail kilobytes (1024 by default). The admin does not upload to the default gallery collection: fill it from your own code.
The collection names are defined in config/shopper/media.php under the storage key (uploads and thumbnail by default). The getFirstMediaUrl method returns the URL for the first media in a collection. If no media has been uploaded, a fallback URL is returned instead. You can also request a specific conversion size like medium (500x500) or large (800x800), defined under shopper.media.conversions.
To display a category's thumbnail on your storefront:
use Shopper\Models\Category;
$category = Category::query()->find($id);
$collection = config('shopper.media.storage.thumbnail_collection');
$thumbnailUrl = $category->getFirstMediaUrl($collection);
$mediumUrl = $category->getFirstMediaUrl($collection, 'medium');To add a thumbnail to a category programmatically:
$collection = config('shopper.media.storage.thumbnail_collection');
$category->addMedia($pathToImage)
->toMediaCollection($collection);Relationships
Parent Category
Every category can optionally belong to a parent category. Use this to build breadcrumbs or display the parent context. Ancestors carry a negative depth (-1 for the parent, -2 for the grandparent), so ordering by depth lists the root category first:
$category->parent;
if ($category->parent) {
$breadcrumb = $category->ancestors()->orderBy('depth')->get();
}Child Categories
Using the laravel-adjacency-list package, categories expose a full set of hierarchical relationships:
The children relationship returns direct children only. Use descendants for all recursive children (children of children, etc.) and ancestors for all recursive parents up to the root.
$category->children;
$category->descendants;
$category->ancestors;
$category->descendantsAndSelf;Descendant Categories
To work with every category below a given one, at any depth, use the descendants relationship. It is an Eloquent relation like children: you can eager load it, count it, or add constraints before running the query. Use descendantsAndSelf to include the category itself.
$total = $category->descendants()->count();
$enabledDescendants = $category->descendants()->enabled()->get();
$categories = Category::query()
->whereNull('parent_id')
->with('descendants')
->get();Products
Categories have a polymorphic many-to-many relationship with products through the product_has_relations table:
$category->products;
$category->products()->count();
$category->products()->publish()->get();Available Tree Methods
The laravel-adjacency-list package provides these methods for traversing the hierarchy:
| Method | Description |
|---|---|
ancestors() | The model's recursive parents |
ancestorsAndSelf() | The model's recursive parents and itself |
bloodline() | The model's ancestors, descendants and itself |
children() | The model's direct children |
childrenAndSelf() | The model's direct children and itself |
descendants() | The model's recursive children |
descendantsAndSelf() | The model's recursive children and itself |
parent() | The model's direct parent |
parentAndSelf() | The model's direct parent and itself |
rootAncestor() | The model's topmost parent |
siblings() | The parent's other children |
siblingsAndSelf() | All the parent's children |
$ancestors = Category::query()->find($id)->ancestors;
$categories = Category::with('descendants')->get();
$total = Category::query()->find($id)->descendants()->count();
Category::query()->find($id)->descendants()->update(['is_enabled' => false]);Query Scopes
Enabled Categories
Filter categories that are visible to customers:
Category::query()->enabled()->get();Root Categories
Get only top-level categories (those without a parent):
Category::query()->whereNull('parent_id')->get();Using the tree structure to get the full hierarchy:
Category::tree()->get();Custom Paths & Slug Behavior
The model declares a slug_path custom path for nested URLs. The laravel-adjacency-list package fills it on categories loaded through a recursive query (tree(), descendants, ancestors and the other tree relations) by joining the slugs with /, starting at the first level of that query. A category loaded with find() or findBySlug() has no slug_path.
With Category::tree(), the path starts at the root. For a category "Laptops" under "Computers" under "Electronics", slug_path is electronics/electronics-computers/electronics-computers-laptops, because each subcategory slug already starts with its parent's slug (see the note below):
public function getCustomPaths(): array
{
return [
[
'name' => 'slug_path',
'column' => 'slug',
'separator' => '/',
],
];
}When a category has a parent, the CategoryObserver sets its slug to the parent's slug followed by the category name, on creation and on every update made through the model. For example, creating a "Laptops" category under a parent with slug electronics-computers produces the slug electronics-computers-laptops, and a slug you pass for a subcategory is replaced. This keeps same-named subcategories under different parents apart (electronics-phones-accessories, electronics-audio-accessories). If a slug is still taken, the HasSlug trait appends -1, -2, etc.
Methods & Helpers
Find by Slug
The findBySlug static method looks up a category by its slug and throws a ModelNotFoundException if not found. It does not check is_enabled:
use Shopper\Models\Category;
$category = Category::findBySlug('electronics');Label with Path
The getLabelOptionName() method returns the full hierarchical path as a formatted string, useful for select dropdowns and admin interfaces:
For a category "Laptops" nested under "Computers" under "Electronics", the method returns Electronics / Computers / Laptops. It walks up the parent relation, which runs one query per level unless the parents are already loaded.
$category->getLabelOptionName();Status Management
Toggle a category's visibility with updateStatus():
Pass true (the default) to enable a category or false to disable it.
$category->updateStatus(true);
$category->updateStatus(false);Creating Categories
Create a root category by omitting the parent_id. Pass the slug yourself, because the model does not build it from the name:
$electronics = Category::query()->create([
'name' => 'Electronics',
'slug' => 'electronics',
'is_enabled' => true,
'position' => 1,
]);Create a subcategory by setting parent_id. The CategoryObserver sets its slug from the parent's slug and the name, electronics-computers here:
$computers = Category::query()->create([
'name' => 'Computers',
'parent_id' => $electronics->id,
'is_enabled' => true,
]);Retrieving Categories
Root categories with their children:
$categories = Category::query()
->whereNull('parent_id')
->enabled()
->with('children')
->orderBy('position')
->get();Full category tree:
$tree = Category::query()
->enabled()
->tree()
->get()
->toTree();A category with all its descendants:
$category = Category::query()
->where('slug', 'electronics')
->with('descendants')
->first();
$breadcrumb = $category->ancestors()->orderBy('depth')->get();For navigation menus with nested enabled children:
$navCategories = Category::query()
->whereNull('parent_id')
->enabled()
->with(['children' => fn ($q) => $q->enabled()])
->orderBy('position')
->get();Working with Products
Products in this category only:
$category = Category::query()->find($id);
$products = $category->products;Products in category and all descendants:
$categoryIds = $category->descendants->pluck('id')->push($category->id);
$products = Product::query()
->publish()
->whereHas('categories', fn ($q) => $q->whereIn('id', $categoryIds))
->get();Metadata
The metadata JSON column lets you store arbitrary key-value data on a category without modifying the schema. This is useful for storing custom attributes like banner colors, display preferences, or integration identifiers:
$category = Category::query()->create([
'name' => 'Summer Sale',
'slug' => 'summer-sale',
'is_enabled' => true,
'metadata' => [
'banner_color' => '#FF6B35',
'featured_on_homepage' => true,
'external_id' => 'cat_abc123',
],
]);
$color = $category->metadata['banner_color'];Disabling Category Feature
If your store doesn't use categories, you can disable the feature entirely. This removes the category menu and pages from the admin panel, and the category field from the product forms:
In your config/shopper/features.php file, set the category feature to disabled:
use Shopper\Enum\FeatureState;
return [
'category' => FeatureState::Disabled,
];Permissions
The permissions seeder creates five permissions for category management:
| Permission | Description |
|---|---|
browse_categories | View the categories list and the Categories menu entry |
read_categories | View a single category. Not checked by the admin category screens |
add_categories | Create new categories |
edit_categories | Edit existing categories, change their status and reorder them |
delete_categories | Delete categories |
Components
You can publish the Livewire components to customize the admin UI for categories:
php artisan shopper:component:publish categoryCreates config/shopper/components/category.php:
use Shopper\Livewire;
return [
'pages' => [
'category-index' => Livewire\Pages\Category\Index::class,
],
'components' => [
'slide-overs.category-form' => Livewire\SlideOvers\CategoryForm::class,
'slide-overs.re-order-categories' => Livewire\SlideOvers\ReOrderCategories::class,
],
];Storefront Example
Here is a complete controller for displaying categories and their products on your storefront. The show method collects products from the category and all its descendants, so browsing "Electronics" also returns products from "Computers", "Laptops", etc.
namespace App\Http\Controllers;
use Shopper\Models\Category;
use Shopper\Models\Product;
class CategoryController extends Controller
{
public function index()
{
$categories = Category::query()
->whereNull('parent_id')
->enabled()
->with(['children' => fn ($q) => $q->enabled()])
->withCount('products')
->orderBy('position')
->get();
return view('categories.index', compact('categories'));
}
public function show(string $slug)
{
$category = Category::findBySlug($slug);
abort_unless($category->is_enabled, 404);
$category->load(['ancestors' => fn ($query) => $query->orderBy('depth')]);
$categoryIds = $category->descendants
->pluck('id')
->push($category->id);
$products = Product::query()
->publish()
->whereHas('categories', fn ($q) => $q->whereIn('id', $categoryIds))
->paginate(12);
return view('categories.show', compact('category', 'products'));
}
}Last updated on
Edit on GitHub