Skip to content

Data Model and Extension Points

Linked Products stores Linked Product Groups in three tables and keeps them consistent with observers and plugins on the catalog. This page covers where the data lives, which PHP interfaces read and write it, and how to manage groups from code and deployment scripts.

Linked Products Database Tables

Grouping data lives in three tables, all keyed by the product entity_id:

Table What it holds
hyva_commerce_linked_group One row per group: group_id, group_name, created_at, updated_at
hyva_commerce_linked_group_attribute The group's link attributes, as group_id and attribute_id pairs
hyva_commerce_linked_group_product The group's products, as group_id and product_id pairs

A unique key on hyva_commerce_linked_group_product.product_id is what keeps a product in one group at most, and one on hyva_commerce_linked_group.group_name keeps group names unique (case-insensitively, by the column's utf8mb4_general_ci collation). Foreign keys cascade deletes from groups, attributes, and products.

On Adobe Commerce, the tables have no staging columns: groups are global and not versioned. The product page still resolves members in the active or previewed version, because membership uses the version-independent entity_id.

Linked Products PHP Interfaces

Two interfaces in Hyva\LinkedProducts\Api read and write groups:

  • LinkedGroupProductRepositoryInterface - group membership: the group of a product, the members of a group, creating a group for a product, and saving members from a product or from a group. Nothing in the module deletes a group on its own: only the admin delete actions, an import with the Delete behavior, and bin/magento hyva:linked-products:dedupe-group-names --remove do.
  • LinkedGroupAttributeRepositoryInterface - link attributes: reading and saving the attribute codes of a product's group or of a group.

Internal Interfaces, Not Service Contracts

These interfaces are the module's own seams. They are not REST or GraphQL endpoints, and they may change between releases. For moving groups between systems, use the CSV format, which is the stable contract.

Linked Products dispatches no events of its own and adds no REST or GraphQL endpoints.

How Linked Products Keeps Groups Consistent

These observers and plugins keep groups in step with the catalog:

Hook Area What it does
catalog_product_save_after global Saves the Linked Products section of the Product Edit page, adds a duplicated product to the original's group, and skips saves inside a Scheduled Update
Plugin on Magento\Catalog\Controller\Adminhtml\Product\Initialization\Helper adminhtml Copies the Linked Products section's fields onto the product being saved, so configurable children saved in the same request keep their own groups
layout_load_before frontend Adds the Linked Products layout handles to the product page
hyva_config_generate_before frontend Registers the module for Tailwind compilation
Plugins on Magento\ImportExport\Controller\Adminhtml\Import\Validate and Start adminhtml Show the import's product-move notices and shared-values warnings, which the Import page lists only when a file has errors

The product form section itself is the linked modifier in the Magento\Catalog\Ui\DataProvider\Product\Form\Modifier\Pool virtual type.

Managing Linked Product Groups from Scripts

For deployments and integrations, drive groups with the CSV import rather than writing to the tables. Groups are the hyva_linked_groups entity of Magento's import framework (Hyva\LinkedProducts\Model\Import\LinkedGroups), so Adobe Commerce Scheduled Import/Export and other tools built on that framework can run it too. The importer validates every row, applies each row in a transaction, and reports what it did:

# Check the file first, then apply it
bin/magento hyva:linked-products:import var/import/linked-product-groups.csv --dry-run
bin/magento hyva:linked-products:import var/import/linked-product-groups.csv

See Importing and Exporting Groups for the file format, the --behavior and --force options, and the validation rules.