Skip to content

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

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
namestringno-Brand name
slugstringyesnullURL-friendly identifier (unique)
websitestringyesnullBrand's official website URL
descriptionlongtextyesnullBrand description (supports rich text)
positionsmallint (unsigned)no0Display order position (set by drag and drop in the admin brands table)
is_enabledbooleannofalseBrand visibility status
seo_titlestring(60)yesnullSEO meta title
seo_descriptionstring(160)yesnullSEO meta description
metadatajsonbyesnullAdditional custom data
created_attimestampyesnullCreation timestamp
updated_attimestampyesnullLast 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); // disable

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

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

PermissionDescription
browse_brandsView the brands list and its sidebar item
read_brandsView a single brand (the admin has no brand detail page and does not check it)
add_brandsCreate new brands
edit_brandsEdit existing brands, reorder them, and enable or disable them in bulk
delete_brandsDelete brands, one at a time or in bulk

Components

To customize the admin UI for brand management:

php artisan shopper:component:publish brand

This 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