Product Tags
Organize products with flat, flexible labels for filtering and marketing campaigns.
Tags are simple labels you attach to products for cross-cutting organization. Unlike categories (hierarchical) or collections (manual or rule-based), tags are flat and flexible, ideal for seasonal labels ("Summer 2026"), marketing campaigns ("Flash Sale"), or storefront filtering ("New Arrival", "Best Seller").
Model
The model used is Shopper\Core\Models\ProductTag, stored in the product_tags table (sh_product_tags with the default table prefix). Products, categories and brands have an admin model that you can replace in config/shopper/models.php; tags do not. Product::tags() and the product_tag morph map entry reference ProductTag directly, so the tag model cannot be swapped through configuration. It uses the HasSlug trait, which turns the slug you give it into a unique, URL-friendly value (see Slug Generation).
Database Schema
Tags Table
| Column | Type | Nullable | Default | Description |
|---|---|---|---|---|
id | bigint | no | auto | Primary key |
name | string | no | - | Tag name |
slug | string | yes | null | URL-friendly identifier (unique), see Slug Generation |
created_at | timestamp | yes | null | Creation timestamp |
updated_at | timestamp | yes | null | Last update timestamp |
Pivot Table
Tags use the shared polymorphic product_has_relations pivot table. This is the same table used by categories, collections, channels, and related products. The polymorphic pattern lets all these models share a single pivot table instead of requiring a dedicated join table for each relationship type.
| Column | Type | Nullable | Description |
|---|---|---|---|
product_id | bigint | no | Foreign key to product |
productable_type | string | no | Morph type (e.g. product_tag) |
productable_id | bigint | no | Foreign key to the related model |
Slug Generation
The HasSlug trait normalizes the slug and handles collisions. When you set the slug attribute, the trait runs the value through Str::slug() and checks for uniqueness. If a slug already exists, it appends an incrementing suffix (-1, -2, etc.) until it finds a unique one. A value with no URL-safe characters gets a random 5-character slug.
The trait does not build the slug from the name. Always pass a slug when you create a tag in code: without one the column stays null and findBySlug() cannot find the tag.
use Shopper\Core\Models\ProductTag;
$tag1 = ProductTag::query()->create(['name' => 'New Arrival', 'slug' => 'new-arrival']);
$tag2 = ProductTag::query()->create(['name' => 'New Arrival 2', 'slug' => 'new-arrival']);
// $tag2->slug === 'new-arrival-1' (auto-incremented to avoid collision)The trait also provides a findBySlug() static method that looks up a tag by its slug and throws a ModelNotFoundException if not found (Laravel turns it into a 404 response):
$tag = ProductTag::findBySlug('summer-2026');Relationships
Products
ProductTag::products() is a morphToMany relationship and Product::tags() is its morphedByMany inverse, both through the product_has_relations table.
From the tag side:
$tag->products;
$tag->products()->count();
$tag->products()->attach([$productId1, $productId2]);
$tag->products()->detach($productId);
$tag->products()->sync($productIds);From the product side:
$product->tags;
$product->tags()->attach([$tagId1, $tagId2]);
$product->tags()->sync($tagIds);Creating Tags
To create a tag, provide a name and a slug. The HasSlug trait ensures slug uniqueness automatically:
use Shopper\Core\Models\ProductTag;
$tag = ProductTag::query()->create([
'name' => 'Summer 2026',
'slug' => 'summer-2026',
]);
$tag->products()->attach([$product1->id, $product2->id]);Tags can also be created inline from the product edit form in the admin panel. The tag selection field includes a "Create" option that opens a modal form, so administrators can add new tags without leaving the product page.
In the admin, both this modal and the Tags page fill the slug from the name and keep the slug field read-only. A name whose slug is already taken is rejected by validation instead of receiving a -1 suffix.
Retrieving Tags
To get all tags ordered by name with their product count:
$tags = ProductTag::query()
->withCount('products')
->orderBy('name')
->get();To find a tag by slug with its products:
$tag = ProductTag::findBySlug('summer-2026');
$products = $tag->products()->publish()->paginate(12);To get all tags for a specific product:
$tags = $product->tags;Configuration
Disabling Tags
If you don't need tags in your store, disable the feature in config/shopper/features.php:
use Shopper\Enum\FeatureState;
return [
'tag' => FeatureState::Disabled,
];When disabled, the tag menu item is hidden from the sidebar, tag-related routes are not registered, and the tag selection field is removed from product forms. The ProductTag model, its table and Product::tags() keep working in your own code.
Permissions
The admin panel generates five permissions for tag management, in the products permission group:
| Permission | Description |
|---|---|
browse_tags | Open the Tags page |
read_tags | Created with the others; no admin screen checks it, since tags have no detail page |
add_tags | Create tags from the Tags page |
edit_tags | Edit tags from the Tags page |
delete_tags | Delete tags, one by one or in bulk |
The permissions seeder creates them on a fresh install. An installation that started before Shopper 2.3 creates them with Shopper\Models\Permission::generate('tags', 'products'), then assigns them to its roles, as described in the 2.2 to 2.3 upgrade guide.
Components
Tags are managed under the product components configuration. To customize the admin UI:
php artisan shopper:component:publish productThis creates config/shopper/components/product.php. The tag page is registered there under the tag-index key, next to the product pages. Point the key to your own Livewire component to replace the page:
return [
'pages' => [
'tag-index' => \Shopper\Livewire\Pages\Tag\Index::class,
],
];To add content above or below the tags table without replacing the page, use the TAGS_TABLE_BEFORE and TAGS_TABLE_AFTER constants of Shopper\View\CatalogRenderHook as render hooks.
Storefront Example
This example shows a tag listing page and a tag detail page that displays all published products for a given tag.
namespace App\Http\Controllers;
use Shopper\Core\Models\ProductTag;
use Shopper\Models\Product;
class TagController extends Controller
{
public function index()
{
$tags = ProductTag::query()
->withCount('products')
->orderBy('name')
->get();
return view('tags.index', compact('tags'));
}
public function show(string $slug)
{
$tag = ProductTag::findBySlug($slug);
$products = $tag->products()
->publish()
->paginate(12);
return view('tags.show', compact('tag', 'products'));
}
}Filtering Products by Tags
To get products that have a specific tag:
$products = Product::query()
->whereHas('tags', fn ($query) => $query->where('slug', 'summer-2026'))
->publish()
->get();To get products that have any of the given tags:
$products = Product::query()
->whereHas('tags', fn ($query) => $query->whereIn('slug', ['new-arrival', 'best-seller']))
->publish()
->paginate(12);Last updated on
Edit on GitHub