whilesmart/eloquent-brands

Polymorphic branding (name, logo, contact details) attachable to any model for Laravel applications.

1.0.0 2026-06-11 16:54 UTC

Requires

• php: ^8.2
• laravel/framework: ^11.0|^12.0
• whilesmart/eloquent-files: ^1.0
• whilesmart/eloquent-owner-access: ^1.0

Requires (Dev)

• fakerphp/faker: ^1.24
• laravel/pint: ^1.22
• orchestra/testbench: ^9.0|^10.0

MIT

• Whilesmart Team

README

A polymorphic brand kit for Laravel: attach branding (name, contact details, colors, and image assets like logos / emblems / favicons in any format) to any model, scoped to an owner through whilesmart/eloquent-owner-access. Image assets are managed by whilesmart/eloquent-files.

A workspace, organisation, or store can hold many brands (one marked as the default used on documents); each brand carries many assets, each tagged with a role.

Install

composer require whilesmart/eloquent-brands
php artisan migrate

Routes register automatically under the api prefix with auth:sanctum. Set BRANDS_REGISTER_ROUTES=false to mount them yourself.

Attaching a brand to a model

use Whilesmart\Brands\Traits\HasBrands;

class Workspace extends Model
{
    use HasBrands;
}

$workspace->brands()->create([
    'owner_type' => Workspace::class,
    'owner_id'   => $workspace->id,
    'name'    => 'Maison Amani SARL',
    'email'   => '[e-mail]',
    'phone'   => '[phone]',
    'address' => '12 Market St, Douala',
    'website' => 'https://amani.africa',
    'tax_id'  => 'M029817',
    'is_default' => true,
    'colors'  => [
        ['name' => 'Primary', 'value' => '#0B0D07'],
        ['name' => 'Accent',  'value' => '#2E3B8D'],
    ],
]);

$workspace->brands;          // every brand kit
$workspace->defaultBrand;    // the default brand used on documents
$workspace->defaultBrand->assets; // its image assets (Files)

The owner morph is the branded entity (a workspace, org, …). An owner can hold many brands; setting is_default on one demotes the others automatically.

Assets (logos, emblems, …)

Assets are stored via eloquent-files (owned by the brand). Each carries a role (logo, logo-dark, emblem, favicon, wordmark, … — free-form) and an optional label, so a brand kit can hold the same mark in several versions/formats.

Method	Endpoint	Notes
GET	/api/brands	List (filter by owner_*)
POST	/api/brands	Create
GET	/api/brands/{brand}	Show (includes assets)
PUT	/api/brands/{brand}	Update
DELETE	/api/brands/{brand}	Delete
POST	/api/brands/{brand}/assets	Upload an asset (asset file, role, label)
DELETE	/api/brands/{brand}/assets/{file}	Remove an asset

$logo = $brand->assetsByRole('logo')->first();
$logo?->url; // public URL of the asset

Custom model

The Brand model is swappable. Publish the config and point brands.model at your own class (extend the package model to add fields/casts/behaviour):

php artisan vendor:publish --tag=brands-config

UUID keys

Set BRANDS_UUIDS=true before migrating for UUID primary keys and uuid morph columns. This assumes the owner model also uses UUID keys.