Skip to content

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

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
namestringno-Tag name
slugstringyesnullURL-friendly identifier (unique), see Slug Generation
created_attimestampyesnullCreation timestamp
updated_attimestampyesnullLast 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.

ColumnTypeNullableDescription
product_idbigintnoForeign key to product
productable_typestringnoMorph type (e.g. product_tag)
productable_idbigintnoForeign 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:

PermissionDescription
browse_tagsOpen the Tags page
read_tagsCreated with the others; no admin screen checks it, since tags have no detail page
add_tagsCreate tags from the Tags page
edit_tagsEdit tags from the Tags page
delete_tagsDelete 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 product

This 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