Skip to content

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).

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
namestringno-Category name
slugstringyesnullURL-friendly identifier (unique)
descriptionlongtextyesnullCategory description
positionsmallint (unsigned)no0Display order among siblings (set by the admin reorder panel)
is_enabledbooleannofalseCategory visibility status
seo_titlestring(60)yesnullSEO meta title
seo_descriptionstring(160)yesnullSEO meta description
metadatajsonbyesnullAdditional custom data
parent_idbigint (unsigned)yesnullForeign key to the parent category. Set to null when the parent is deleted, so its children become root categories
created_attimestampyesnullCreation timestamp
updated_attimestampyesnullLast 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.

CollectionConfig keyBehaviorDescription
Default galleryshopper.media.storage.collection_nameMultiple filesCategory images
Thumbnailshopper.media.storage.thumbnail_collectionSingle filePrimary 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:

MethodDescription
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:

PermissionDescription
browse_categoriesView the categories list and the Categories menu entry
read_categoriesView a single category. Not checked by the admin category screens
add_categoriesCreate new categories
edit_categoriesEdit existing categories, change their status and reorder them
delete_categoriesDelete categories

Components

You can publish the Livewire components to customize the admin UI for categories:

php artisan shopper:component:publish category

Creates 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