Brands
Manage product brands with logos, SEO metadata, and storefront filtering.
Brands represent manufacturers or labels for your products. They help customers identify and filter products from their favorite manufacturers, and they give your storefront structured navigation (e.g., a "Shop by Brand" page or a brand filter in search results).
Model
The model used is Shopper\Models\Brand, which extends Shopper\Core\Models\Brand. The core model provides the business logic, relationships, scopes, and slug generation. The admin model adds media collections and conversions through Spatie MediaLibrary.
The core model implements Shopper\Core\Models\Contracts\Brand and uses the HasSlug trait for automatic slug generation with collision handling, and the HasMediaCollections trait for config-driven media support.
Extending the Model
To add custom behavior, extend the admin model and update your configuration:
namespace App\Models;
use Shopper\Models\Brand as ShopperBrand;
class Brand extends ShopperBrand
{
}Update config/shopper/models.php:
return [
'brand' => \App\Models\Brand::class,
];Database Schema
| Column | Type | Nullable | Default | Description |
|---|---|---|---|---|
id | bigint | no | auto | Primary key |
name | string | no | - | Brand name |
slug | string | yes | null | URL-friendly identifier (unique) |
website | string | yes | null | Brand's official website URL |
description | longtext | yes | null | Brand description (supports rich text) |
position | smallint (unsigned) | no | 0 | Display order position (set by drag and drop in the admin brands table) |
is_enabled | boolean | no | false | Brand 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 |
created_at | timestamp | yes | null | Creation timestamp |
updated_at | timestamp | yes | null | Last update timestamp |
Slug Generation
The HasSlug trait generates unique slugs automatically. When you set the slug attribute, the trait runs it through Str::slug() and appends an incrementing suffix (-1, -2, etc.) if a collision is detected.
The trait does not build the slug from the name. The admin brand form fills it from the name for you, but when you create a brand in code, pass a slug yourself, otherwise the column stays null.
The trait also provides a findBySlug() static method. It throws a ModelNotFoundException (a 404 response in a controller) when no brand matches, and it does not check is_enabled:
use Shopper\Models\Brand;
$brand = Brand::findBySlug('nike');Relationships
Products
A brand has many products. This is a standard HasMany relationship using the configured product model, through the brand_id column of the products table. Deleting a brand keeps its products and sets their brand_id to null.
$brand->products;
$brand->products()->count();To get only published products for a brand (for storefront display):
$brand->products()->publish()->get();With eager loading:
$brands = Brand::query()->with('products')->get();Query Scopes
Enabled Brands
The enabled scope filters brands where is_enabled is true. Use it for all storefront queries to exclude draft or hidden brands.
use Shopper\Models\Brand;
Brand::query()->enabled()->orderBy('position')->get();Status Management
The updateStatus() method provides a convenient way to toggle brand visibility:
$brand->updateStatus(true); // enable
$brand->updateStatus(false); // disableYou can also update the field directly:
$brand->update(['is_enabled' => true]);The brand select of the admin product forms only lists enabled brands.
Media
Brands 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 | Brand images |
| Thumbnail | shopper.media.storage.thumbnail_collection | Single file | Brand logo |
The collections default to uploads and thumbnail, use the shopper.media.storage.disk_name disk and accept the mime types listed in shopper.media.accepts_mime_types. The admin brand form uploads the logo to the thumbnail collection, up to shopper.media.max_size.thumbnail kilobytes.
To add a brand logo:
$collection = config('shopper.media.storage.thumbnail_collection');
$brand->addMedia($file)->toMediaCollection($collection);To retrieve the logo URL with a specific conversion:
$collection = config('shopper.media.storage.thumbnail_collection');
$url = $brand->getFirstMediaUrl($collection, 'medium');Conversion names come from shopper.media.conversions: large and medium by default (see image conversions). When the brand has no logo, getFirstMediaUrl() returns the Shopper placeholder image, not an empty string. Check $brand->hasMedia($collection) first if your storefront should show the brand name instead.
From a URL:
$collection = config('shopper.media.storage.thumbnail_collection');
$brand->addMediaFromUrl('https://example.com/nike-logo.png')
->toMediaCollection($collection);Creating Brands
To create a brand with a logo and SEO metadata:
use Shopper\Models\Brand;
$brand = Brand::query()->create([
'name' => 'Nike',
'slug' => 'nike',
'website' => 'https://nike.com',
'description' => 'Just Do It',
'is_enabled' => true,
'position' => 1,
'seo_title' => 'Nike - Official Products',
'seo_description' => 'Shop official Nike products including shoes, clothing, and accessories.',
]);
$collection = config('shopper.media.storage.thumbnail_collection');
$brand->addMedia($logoFile)->toMediaCollection($collection);Retrieving Brands
To get all enabled brands ordered by position:
Brand::query()->enabled()->orderBy('position')->get();To get brands that have at least one published product, with their published product counts:
$brands = Brand::query()
->enabled()
->whereHas('products', fn ($query) => $query->publish())
->withCount(['products' => fn ($query) => $query->publish()])
->get();To find a brand by slug:
$brand = Brand::findBySlug('nike');For navigation or filter dropdowns where you only need name and slug:
$brands = Brand::query()
->enabled()
->select(['id', 'name', 'slug'])
->orderBy('name')
->get();Metadata
The metadata JSON column lets you store additional custom data that doesn't warrant its own database column. The model casts it to an array.
The admin brand form edits metadata as a list of key-value pairs with text values. If your team also edits brands in the admin, keep the values flat strings:
$brand->update([
'metadata' => [
'country_of_origin' => 'USA',
'founded_year' => '1964',
'instagram' => '@nike',
],
]);
$country = $brand->metadata['country_of_origin'] ?? null;Configuration
Disabling Brands
If you don't need brands in your store, disable the feature in config/shopper/features.php:
use Shopper\Enum\FeatureState;
return [
'brand' => FeatureState::Disabled,
];When disabled, the brand menu item is hidden from the sidebar, brand-related routes are not registered, brand selection is removed from product forms, and the brand column is hidden from the products table.
Permissions
The admin panel generates five permissions for brand management:
| Permission | Description |
|---|---|
browse_brands | View the brands list and its sidebar item |
read_brands | View a single brand (the admin has no brand detail page and does not check it) |
add_brands | Create new brands |
edit_brands | Edit existing brands, reorder them, and enable or disable them in bulk |
delete_brands | Delete brands, one at a time or in bulk |
Components
To customize the admin UI for brand management:
php artisan shopper:component:publish brandThis creates config/shopper/components/brand.php:
use Shopper\Livewire;
return [
'pages' => [
'brand-index' => Livewire\Pages\Brand\Index::class,
],
'components' => [
'slide-overs.brand-form' => Livewire\SlideOvers\BrandForm::class,
],
];The BrandForm slide-over handles both creating and editing a brand. To add content above or below the brands table without publishing components, use the CatalogRenderHook::BRANDS_TABLE_BEFORE and CatalogRenderHook::BRANDS_TABLE_AFTER render hooks.
Storefront Example
This example shows a brand listing page and a brand detail page with its published products. The detail page queries with the enabled scope so a disabled brand returns a 404.
namespace App\Http\Controllers;
use Shopper\Models\Brand;
class BrandController extends Controller
{
public function index()
{
$brands = Brand::query()
->enabled()
->withCount(['products' => fn ($query) => $query->publish()])
->orderBy('position')
->get();
return view('brands.index', compact('brands'));
}
public function show(string $slug)
{
$brand = Brand::query()
->enabled()
->where('slug', $slug)
->firstOrFail();
$products = $brand->products()
->publish()
->paginate(12);
return view('brands.show', compact('brand', 'products'));
}
}View Composer
For brands that appear in multiple views (header, footer, filters), use a View Composer to avoid repeating the query:
namespace App\View\Composers;
use Illuminate\View\View;
use Shopper\Models\Brand;
class BrandsComposer
{
public function compose(View $view): void
{
$view->with('brands', Brand::query()
->enabled()
->orderBy('position')
->take(12)
->get()
);
}
}Register it in your AppServiceProvider:
use App\View\Composers\BrandsComposer;
use Illuminate\Support\Facades\View;
public function boot(): void
{
View::composer(['partials.brands', 'filters.brands'], BrandsComposer::class);
}Last updated on
Edit on GitHub