The catalog is not EAV. Every product is one row in products with a single JSON values column; attributes, families and groups only describe how that JSON is shaped, validated, rendered, filtered and indexed. A generic-Laravel instinct (a new column, a new table, an attribute_values relation, a PHP enum of types) is wrong at every layer here. Read the exemplar before you write.
REQUIRED BACKGROUND: unopim-standards for idiom, security, scale, localization and comments. unopim-exec to resolve commands. unopim-verify before calling anything done. Package scaffolding, provider wiring and ACL files: unopim-plugin-development. Import/export of catalog data: unopim-data-transfer. Product grid columns: unopim-datagrid.
Reference files
| File | Read when |
|---|---|
| values.md | Reading or writing products.values, scoping by channel/locale/currency, JSON paths, uniqueness, variant read-time inheritance |
| attribute-types.md | Adding an attribute type, or deciding you do not need one; every layer a type touches |
| product-types-variants.md | product_types config, AbstractType, configurable / variant_group trees, variant structures, the two variant commands, associations |
| events.md | Hooking a catalog write — which event fires on which path, payload shapes, import and bulk-edit paths that do not fire them |
Exemplars — copy shape from these
- Values contract and scoping accessors:
packages/Webkul/Attribute/src/Models/Attribute.php - Value keys and the update pipeline:
packages/Webkul/Product/src/Type/AbstractType.php - A package-owned attribute type, every layer wired:
packages/Webkul/Measurement/src/Providers/MeasurementServiceProvider.php - Product type registry:
packages/Webkul/Product/src/Config/product_types.php+packages/Webkul/Product/src/Enums/ProductType.php - A listener that covers admin, API, bulk-edit and import writes:
packages/Webkul/Webhook/src/Listeners/Product.php - Variant inheritance:
packages/Webkul/Product/src/Services/VariantValueResolver.php
Decision procedure
- Need a new kind of value? First check whether an existing type plus attribute settings covers it.
textalready acceptsvalidation=number,email,decimal,urlorregex(packages/Webkul/Attribute/src/Rules/ValidationTypes.php);selectcovers enumerations;pricecovers per-currency amounts. Add a type only when storage shape, editor control, filter semantics or index mapping genuinely differ — then follow attribute-types.md end to end. - Need a new product type? Almost never.
simple,configurableand the internalvariant_groupare hard-wired into variant levels, API requests, importers and grids. Read product-types-variants.md before proposing one. - Reading a value? Go through the attribute (
getValueFromProductValues(),getJsonPath(),getScope()), and for any product with aparent_idreadresolvedValues(), notvalues. See values.md. - Writing a value? Go through
ProductRepository::update()→ the type'supdate(), never$product->values = …; save()from a controller. Variant writes passguardVariantLevelWrite(); skipping it lets a child silently override an axis or an ancestor-owned attribute. - Reacting to a change? Pick the events from events.md for every write path you must cover — admin and API fire
catalog.product.*, the product importer firesdata_transfer.imports.batch.product.*, bulk edit firescatalog.product.bulk.edit.after. - Changing what a family contains? Go through
AttributeFamilyRepositorysocatalog.attribute_family.attributes.changedfires and completeness settings for removed attributes are pruned.
Invented API vs real API
| Invented (does not exist) | Real |
|---|---|
product_attribute_values table, $product->attribute_values() |
one JSON column products.values, cast array on packages/Webkul/Product/src/Models/Product.php |
values['global'], values['default'], values[$locale] |
buckets common, locale_specific, channel_specific, channel_locale_specific plus categories and associations — constants on AbstractType |
AttributeTypeEnum, ProductTypeEnum::Bundle |
config('attribute_types'); Webkul\Product\Enums\ProductType has exactly Simple, Configurable, VariantGroup |
validating a type against AttributeTypes::ATTRIBUTE_TYPES |
the rule validates against array_keys(config('attribute_types')); the constant is stale (no measurement) |
catalog.product.save.after, catalog.attribute_group.update.after |
catalog.product.update.after; group update fires catalog.attribute.group.update.before then catalog.attributegroup.update.after (no dot — core spelling, listen to it as is) |
changing an attribute's type or scope flags after create |
type, code, value_per_locale, value_per_channel, is_unique are dropped from the update payload in packages/Webkul/Admin/src/Http/Controllers/Catalog/AttributeController.php — immutable |
php artisan unopim:variants:sync, --dry-run |
unopim:variants:resync {--product=} {--all}; unopim:variants:strip-redundant {--apply} {--product=} (dry run is the default) |
UnoPim-specific pitfalls
- Portability. Raw JSON SQL goes through
DB::rawQueryGrammar()->jsonExtract()— exemplarpackages/Webkul/Measurement/src/Filter/Database/MeasurementFilter.php. Never hand-write->>/JSON_EXTRACT. PostgreSQL returns booleans and JSON scalars with different types; compare loosely-typed values the wayProductRepository::variantValueEquals()does. Attribute codes reach JSON paths unescaped — accept only^\w+$codes (ProductRepository::isUniqueVariantForProduct()shows the guard). - Prefix.
DB::table('products')is prefix-safe; a raw fragment naming the table needsDB::getTablePrefix()— see unopim-standards. - Elasticsearch optional. A new attribute type needs a database filter AND an Elasticsearch filter tagged in the container; with neither,
ProductQueryFilter::applyFilter()throws "No matching filter found". Index mapping is per type suffix ({code}-{type}); a type absent fromProductIndexer::dynamicAttributeMappings()is dynamically mapped by Elasticsearch from the first value it sees. Reindex withunopim:product:index --freshafter shipping a type. - Octane / queue workers.
ElasticSearch\Observers\Product::disable()andCompleteness\Observers\Product::disable()flip static flags. Re-enable infinally, exactly aspackages/Webkul/DataTransfer/src/Helpers/Importers/Product/Importer.phpdoes, or every later save in the worker stops indexing and scoring. - ACL. Catalog keys are
catalog.attributes.*,catalog.families.*,catalog.products.*,catalog.association_types.*inpackages/Webkul/Admin/src/Config/acl.php. Any new catalog route you add must map to one; enforcement is fail-open by route name — see unopim-plugin-development acl-security.md. - Localization. Attribute-type and product-type
namevalues are translation keys; a package-owned type uses its own namespace (measurement::app.attribute.measurement) and ships all 33 locales. - Scale.
productsholds millions of rows. Variant maintenance runschunkById(200)and queues completeness; any catalog backfill you write does the same — see unopim-standards scale.md.
Verification
Run unopim-verify. Catalog-specific checks on top of the six gates:
- Pest covers both
elasticsearch.enabledbranches for any filter, and both MySQL and PostgreSQL for any raw JSON SQL (phpunit.pgsql.xml). - A new attribute type has a test that creates an attribute of that type through
Attribute::factory(), saves a product value in each of the four scopes, and reads it back — model it onpackages/Webkul/Attribute/tests/Unit/Models/AttributeTest.php. - Variant changes:
packages/Webkul/Product/tests/Unit/Models/ResolvedValuesTest.phpand the two command tests underpackages/Webkul/Product/tests/Unit/Console/still pass. - Product-form changes are UI changes — run the Playwright gate.