bagisto-attribute-development

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

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:

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:

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.