Skip to content

Attributes

Complete reference for the Attribute model, field types, values, and usage in Shopper.

Attributes define product characteristics like Color, Size, or Material. They enable variable products, enhance filtering, and provide detailed product specifications.

Models

Shopper uses three models to manage attributes:

ModelPurpose
Shopper\Core\Models\AttributeThe attribute definition (Color, Size, Material)
Shopper\Core\Models\AttributeValuePossible values for an attribute (Red, Blue, Large)
Shopper\Core\Models\AttributeProductPivot linking attributes to products with a selected value or a custom value

The Attribute model implements Shopper\Core\Models\Contracts\Attribute and uses the HasSlug trait, which turns the slug you set into a unique slug. Unlike products or brands, the Attribute model is not configurable via config/shopper/models.php and has no admin model wrapper.

Database Schema

Table names start with the prefix set in config('shopper.core.table_prefix') (sh_ by default), for example sh_attributes.

Attribute Table

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
namestringno-Attribute name
slugstringyesnullURL-friendly identifier (unique), not generated from name
descriptionstringyesnullAttribute description
typestringno-Field type enum value
iconstringyesnullIcon identifier
is_enabledbooleannofalseOnly enabled attributes can be added to a product in the admin
is_searchablebooleannofalseFlag for your storefront search (Shopper does not read it)
is_filterablebooleannofalseFlag for your storefront filters (Shopper does not read it)
created_attimestampyesnullCreation timestamp
updated_attimestampyesnullLast update timestamp

AttributeValue Table

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
valuestring(50)no-Display value
keystringno-Identifier, unique per attribute (the hex code for a ColorPicker attribute)
positionunsigned smallintyes1Display order
attribute_idbigintno-Foreign key to attribute

AttributeProduct Table (Pivot)

ColumnTypeNullableDescription
idbigintnoPrimary key
attribute_idbigintnoForeign key to attribute
product_idbigintnoForeign key to product
attribute_value_idbigintyesForeign key to attribute value
attribute_custom_valuelongtextyesCustom value for text-based attributes

Field Types

Attributes use the FieldType enum to determine input behavior:

use Shopper\Core\Enum\FieldType;

FieldType::Checkbox;     // Multiple selectable values
FieldType::ColorPicker;  // Multiple selectable colors
FieldType::DatePicker;   // Date input
FieldType::RichText;     // Rich text editor
FieldType::Select;       // Single selection dropdown
FieldType::Text;         // Single-line text input
FieldType::Number;       // Numeric value
TypeDatabase ValueHas Predefined ValuesDescription
CheckboxcheckboxYesMultiple values can be selected
ColorPickercolorpickerYesMultiple color values, each with a hex code
DatePickerdatepickerNoDate input field
RichTextrichtextNoHTML content editor
SelectselectYesSingle value selection
TexttextNoFree text input
NumbernumberNoNumeric value, entered in a text input

Types without predefined values store the product's value as text in attribute_custom_value: HTML for RichText, a Y-m-d date for DatePicker.

Type Checking Methods

Each attribute type has helper methods to determine its behavior:

$attribute->hasMultipleValues();
$attribute->hasSingleValue();
$attribute->hasTextValue();
Attribute::fieldsWithValues();

hasMultipleValues() returns true for Checkbox and ColorPicker. hasSingleValue() returns true for Select. hasTextValue() returns true for Text, Number, RichText, and DatePicker. fieldsWithValues() returns the types that take predefined values: Checkbox, ColorPicker and Select. The admin shows the Values action only for these types.

Relationships

Values

$attribute->values;

To add values to an attribute (key must be unique within the attribute, value holds up to 50 characters):

$attribute->values()->create([
    'value' => 'Organic Cotton',
    'key' => 'organic-cotton',
    'position' => 1,
]);
$attribute->values()->createMany([
    ['value' => 'Small', 'key' => 'size-s', 'position' => 1],
    ['value' => 'Medium', 'key' => 'size-m', 'position' => 2],
    ['value' => 'Large', 'key' => 'size-l', 'position' => 3],
]);

Products

$attribute->products;

Attach an attribute to a product with a predefined value:

$attribute->products()->attach($productId, [
    'attribute_value_id' => $valueId,
]);

Or with a custom value:

$attribute->products()->attach($productId, [
    'attribute_custom_value' => 'Custom specification',
]);

Variants (AttributeValue)

AttributeValue can be linked to product variants:

$attributeValue->variants;
$attributeValue->variants()->attach($variantId);

The link is stored in the attribute_value_product_variant table (value_id, variant_id). From the variant side, values() returns the attribute values of a ProductVariant:

$variant->values;

Slug & Lookup

When you set slug, the HasSlug trait passes it through Str::slug() and appends -1, -2 and so on if another attribute already uses it. It does not build the slug from name, so pass slug when you create an attribute. The trait also provides a findBySlug() static method, which throws a ModelNotFoundException when no attribute matches:

use Shopper\Core\Models\Attribute;

$attribute = Attribute::findBySlug('color');

Query Scopes

Filter attributes by their visibility and behavior flags:

use Shopper\Core\Models\Attribute;

Attribute::query()->enabled()->get();
Attribute::query()->isFilterable()->get();
Attribute::query()->isSearchable()->get();

Scopes can be combined:

Attribute::query()
    ->enabled()
    ->isFilterable()
    ->with('values')
    ->get();

Status Management

$attribute->updateStatus(true);
$attribute->updateStatus(false);

updateStatus() writes is_enabled and defaults to true.

Display Helpers

$attribute->type_formatted;
Attribute::typesFields();

type_formatted returns the translated label of the type, like "Checkbox" or "Color picker". typesFields() returns every type as a value => label array, like ['checkbox' => 'Checkbox', 'colorpicker' => 'Color picker', ...].

Working with AttributeProduct

Each AttributeProduct row has attribute, product and value relationships, and a computed real_value accessor:

use Shopper\Core\Models\AttributeProduct;

$attributeProduct = AttributeProduct::query()->find($id);

// Get the actual value (custom or from value relationship)
$attributeProduct->real_value;
// Returns attribute_custom_value if set, otherwise value->value

Creating Attributes

Attribute with Predefined Values

use Shopper\Core\Models\Attribute;
use Shopper\Core\Enum\FieldType;

// Create a color attribute
$color = Attribute::query()->create([
    'name' => 'Color',
    'slug' => 'color',
    'type' => FieldType::ColorPicker,
    'is_enabled' => true,
    'is_filterable' => true,
]);

// Add color values
$color->values()->createMany([
    ['value' => 'Red', 'key' => '#dc2626', 'position' => 1],
    ['value' => 'Blue', 'key' => '#2563eb', 'position' => 2],
    ['value' => 'Green', 'key' => '#16a34a', 'position' => 3],
]);

For a ColorPicker attribute, key holds the hex code: the admin edits it with a color picker and draws the swatch from it. value is the color name.

Attribute with Free Text

// Create a text attribute (no predefined values needed)
$material = Attribute::query()->create([
    'name' => 'Material',
    'slug' => 'material',
    'type' => FieldType::Text,
    'is_enabled' => true,
    'is_searchable' => true,
]);

Assigning Attributes to Products

On the product side the relationship is options(), because attributes is already a property of every Eloquent model. A Checkbox or ColorPicker attribute takes one row per selected value, so $product->options returns that attribute once per value. In the admin, the Attributes tab appears on standard, variant and virtual products, not on external ones.

use Shopper\Models\Product;

$product = Product::query()->find($id);

// Assign attribute with predefined value (via options relationship)
$product->options()->attach($attributeId, [
    'attribute_value_id' => $valueId,
]);

// Assign several values of a Checkbox or ColorPicker attribute: one row per value
foreach ($valueIds as $valueId) {
    $product->options()->attach($attributeId, [
        'attribute_value_id' => $valueId,
    ]);
}

// Assign attribute with custom value
$product->options()->attach($attributeId, [
    'attribute_custom_value' => '100% Cotton',
]);

// Get product attributes with values
foreach ($product->options as $attribute) {
    $valueId = $attribute->pivot->attribute_value_id;
    $customValue = $attribute->pivot->attribute_custom_value;
}

Retrieving Attributes

use Shopper\Core\Models\Attribute;

// Get all enabled attributes with values
$attributes = Attribute::query()
    ->enabled()
    ->with('values')
    ->get();

// Get filterable attributes for storefront
$filters = Attribute::query()
    ->enabled()
    ->isFilterable()
    ->with(['values' => fn ($q) => $q->orderBy('position')])
    ->get();

// Get attribute by slug
$size = Attribute::findBySlug('size');
$size->load('values');

Observer Behavior

The AttributeObserver handles cleanup when deleting:

// When an attribute is deleted:
// 1. All product associations are detached
// 2. All attribute values are deleted

$attribute->delete(); // Triggers observer cleanup

Disabling Attribute Feature

// config/shopper/features.php
use Shopper\Enum\FeatureState;

return [
    'attribute' => FeatureState::Disabled,
];

This removes the Attributes page, its menu entry and the Attributes tab of the product page. The models and their data stay.

Permissions

The admin panel generates five permissions for attribute management:

PermissionDescription
browse_attributesView the attributes list
read_attributesView a single attribute
add_attributesCreate new attributes
edit_attributesEdit existing attributes
delete_attributesDelete attributes

Components

Attribute components are part of the product configuration. To customize them:

php artisan shopper:component:publish product

Attribute-related components in config/shopper/components/product.php:

use Shopper\Livewire;
use Shopper\Livewire\Components;

return [
    'pages' => [
        // ...
        'attribute-index' => Livewire\Pages\Attribute\Browse::class,
    ],
    'components' => [
        // ...
        'products.form.attributes' => Components\Products\Form\Attributes::class,
        'slide-overs.attribute-form' => Livewire\SlideOvers\AttributeForm::class,
        'slide-overs.choose-product-attributes' => Livewire\SlideOvers\ChooseProductAttributes::class,
        'slide-overs.attribute-values' => Livewire\SlideOvers\AttributeValues::class,
    ],
];

Storefront Example

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Shopper\Core\Models\Attribute;
use Shopper\Models\Product;

class ProductFilterController extends Controller
{
    public function index()
    {
        // Get filterable attributes for sidebar
        $filters = Attribute::query()
            ->enabled()
            ->isFilterable()
            ->with(['values' => fn ($q) => $q->orderBy('position')])
            ->get();

        return view('products.index', compact('filters'));
    }

    public function filter(Request $request)
    {
        $query = Product::query()->publish();

        foreach ($request->input('attributes', []) as $slug => $values) {
            $query->whereHas('options', function ($q) use ($slug, $values) {
                $q->where('slug', $slug)
                    ->whereIn(shopper_table('attribute_product').'.attribute_value_id', $values);
            });
        }

        return $query->paginate(12);
    }
}

Use Cases

Attribute TypeExampleUse Case
CheckboxSizeMultiple sizes available for clothing
ColorPickerColorProduct color options
SelectMaterialSingle material selection
TextSKU SuffixCustom text per product
NumberWeightNumeric specifications
DatePickerRelease DateProduct launch date
RichTextCare InstructionsDetailed HTML content

Last updated on

Edit on GitHub