bagisto-attribute-development

name	bagisto-attribute-development
description	Use when working with Bagisto's EAV attribute system — adding or changing an attribute, attribute family or group, reading or writing a product attribute value, or debugging a value that reads back empty or from the wrong locale or channel. Trigger phrases include "attribute", "EAV", "attribute family", "attribute group", "attribute option", "custom attribute", "value_per_locale", "value_per_channel", "product_flat", "swatch".
requires	bagisto-coding-standards
license	MIT

Attribute Development

Bagisto stores product data as EAV — entity, attribute, value — rather than as columns on products. A product row carries almost nothing; its name, price, description and every custom field live in product_attribute_values, one row per attribute per locale per channel.

This is the concept most Bagisto mistakes trace back to, so it is worth reading eav.md before changing anything that touches product data.

Reference files

File	Load when
eav.md	How values are stored and resolved — the column map, scope, the flat index
attributes.md	Creating attributes, families, groups, options, validation and swatches

The shape

attribute_families            a product type's whole form  (e.g. "Default")
  └── attribute_groups        a tab/section within it      (e.g. "General")
        └── attributes        a field                      (e.g. "name")
              └── attribute_options   for select, multiselect and checkbox

A product belongs to one family, and that family decides which attributes it has. AttributeFamily::custom_attributes() and AttributeGroup::custom_attributes() are the relations that walk it.

The column map

An attribute's type decides which column of product_attribute_values holds its value:

type	column
text, textarea, multiselect, checkbox, file, image	text_value
price	float_value
boolean	boolean_value
select	integer_value
date	date_value
datetime	datetime_value

This map lives on Attribute::$attributeTypeFields, and the model exposes the resolved name as $attribute->column_name. Never guess the column — read it from the attribute, or a select silently writes into text_value and reads back as null.

AttributeTypeEnum is the authoritative list of types; ValidationEnum (numeric, email, decimal, url, regex) and SwatchTypeEnum (dropdown, color, image, text) cover the rest.

Scope: the two flags that cause most bugs

Every attribute carries value_per_locale and value_per_channel. Together they decide how many rows a single attribute has for one product, and which one a read returns:

value_per_channel	value_per_locale	Rows per product
false	false	1
false	true	one per locale
true	false	one per channel
true	true	one per channel per locale

Product::getCustomAttributeValue() resolves the right row for the requested channel and locale, falling back to the default channel and locale when the requested one is empty. A value that "disappears" on a second locale is almost always an attribute written without honouring these flags.

The table enforces this with a unique index on (channel, locale, attribute_id, product_id), so writing the wrong scope combination is a constraint violation rather than a silent duplicate.

Non-negotiables

• Go through the repository. AttributeRepository, AttributeFamilyRepository, AttributeGroupRepository, AttributeOptionRepository — never write product_attribute_values by hand.
• Read the column from the attribute, via column_name or $attributeTypeFields. A hard-coded column is a bug waiting for the first non-text attribute.
• Honour value_per_locale and value_per_channel on every write, not just on read. Writing one row for an attribute scoped per locale loses every other locale's value.
• A select/multiselect value is an option id, not the label. select stores one id in integer_value; multiselect stores comma-separated ids in text_value.
• Option labels are translatable — they live in attribute_option_translations, so a label added in one locale must be added in all 22.
• Changing an attribute's type orphans its existing values, because the new type reads a different column. Treat it as a data migration, not an edit.
• Reindex after a change that affects listing. Filterable and listing attributes are denormalised into product_flat by the flat indexer; until it runs, the grid and storefront show the old value.

REQUIRED SUB-SKILL: Use bagisto-change-verification before calling any change done.