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:
| Model | Purpose |
|---|---|
Shopper\Core\Models\Attribute | The attribute definition (Color, Size, Material) |
Shopper\Core\Models\AttributeValue | Possible values for an attribute (Red, Blue, Large) |
Shopper\Core\Models\AttributeProduct | Pivot 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
| Column | Type | Nullable | Default | Description |
|---|---|---|---|---|
id | bigint | no | auto | Primary key |
name | string | no | - | Attribute name |
slug | string | yes | null | URL-friendly identifier (unique), not generated from name |
description | string | yes | null | Attribute description |
type | string | no | - | Field type enum value |
icon | string | yes | null | Icon identifier |
is_enabled | boolean | no | false | Only enabled attributes can be added to a product in the admin |
is_searchable | boolean | no | false | Flag for your storefront search (Shopper does not read it) |
is_filterable | boolean | no | false | Flag for your storefront filters (Shopper does not read it) |
created_at | timestamp | yes | null | Creation timestamp |
updated_at | timestamp | yes | null | Last update timestamp |
AttributeValue Table
| Column | Type | Nullable | Default | Description |
|---|---|---|---|---|
id | bigint | no | auto | Primary key |
value | string(50) | no | - | Display value |
key | string | no | - | Identifier, unique per attribute (the hex code for a ColorPicker attribute) |
position | unsigned smallint | yes | 1 | Display order |
attribute_id | bigint | no | - | Foreign key to attribute |
AttributeProduct Table (Pivot)
| Column | Type | Nullable | Description |
|---|---|---|---|
id | bigint | no | Primary key |
attribute_id | bigint | no | Foreign key to attribute |
product_id | bigint | no | Foreign key to product |
attribute_value_id | bigint | yes | Foreign key to attribute value |
attribute_custom_value | longtext | yes | Custom 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| Type | Database Value | Has Predefined Values | Description |
|---|---|---|---|
| Checkbox | checkbox | Yes | Multiple values can be selected |
| ColorPicker | colorpicker | Yes | Multiple color values, each with a hex code |
| DatePicker | datepicker | No | Date input field |
| RichText | richtext | No | HTML content editor |
| Select | select | Yes | Single value selection |
| Text | text | No | Free text input |
| Number | number | No | Numeric 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->valueCreating 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 cleanupDisabling 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:
| Permission | Description |
|---|---|
browse_attributes | View the attributes list |
read_attributes | View a single attribute |
add_attributes | Create new attributes |
edit_attributes | Edit existing attributes |
delete_attributes | Delete attributes |
Components
Attribute components are part of the product configuration. To customize them:
php artisan shopper:component:publish productAttribute-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 Type | Example | Use Case |
|---|---|---|
| Checkbox | Size | Multiple sizes available for clothing |
| ColorPicker | Color | Product color options |
| Select | Material | Single material selection |
| Text | SKU Suffix | Custom text per product |
| Number | Weight | Numeric specifications |
| DatePicker | Release Date | Product launch date |
| RichText | Care Instructions | Detailed HTML content |
Last updated on
Edit on GitHub