Download the PHP package magendoo/module-product-labels without Composer

Magendoo ProductLabels

Product labels ("Sale", "New", "Staff Pick", …) for Magento 2.4.x, rendered as badges on category listings and product pages, exposed in GraphQL, and driven by a first-class label entity with a stable code — not by ad-hoc attribute options.

Why this module is shaped the way it is

• Labels are entities, not attribute options. Every label has a stable code (e.g. sale, new-arrival) that stays identical across environments and is the only identifier integrations should use. Numeric IDs are local to one installation.
• Manual and computed assignments never share storage. Merchandisers assign labels on the product form (a multiselect attribute the module never writes). Rule-computed assignments are materialized by an indexer into a dedicated table. A rule recalculation can never overwrite a merchandiser's selection, and a product import can never wipe computed labels.
• The storefront reads materialized data only. Category and search listings are preloaded in one batch — two indexed lookups for the whole page, no rule evaluation, no external calls in the render path. Related/up-sell blocks and product widgets fall back to two lookups per tile (batched preload for those surfaces is on the roadmap).

Features

• Label definitions with admin grid and form: code, name, text, colors, corner position, per-placement visibility (listing / product page), priority, active flag.
• Store-view text overrides (e.g. translate "Sale" per store view).
• Manual assignment via the Product Labels multiselect on the product form (Product Details section, global scope).
• Two built-in computed rules, recalculated by a real Magento indexer with MView change tracking:
  • New products — the product's Set Product as New From/To window is active.
  • On sale — the product has an active special price window and the special price is below the regular price.
• Luma rendering on category listings, search results and product pages (badge overlay, four corner positions, stacked when several labels share a corner).
• GraphQL: magendoo_labels on every product in the products query.
• Full-page-cache aware: pages carry identity tags for the labels they render, listing pages are stamped with every label so visibility transitions flush in both directions, manual assignees' product pages are flushed when a label's visibility changes, and the indexer flushes exactly the products whose computed label set changed.

Requirements

• Magento Open Source / Adobe Commerce 2.4.x (magento/framework ≥ 103)
• PHP 8.2, 8.3 or 8.4

Installation

The setup:upgrade creates three tables (magendoo_product_label, magendoo_product_label_store, magendoo_product_label_assignment), the magendoo_product_labels product attribute, and registers the Product Labels indexer.

Configuration

Stores → Configuration → Magendoo → Product Labels

Managing labels

Marketing → Promotions → Product Labels

Each label has:

• Code — stable identifier, lowercase letters/digits/_/-, unique. Used by GraphQL and any integration. Choose it once and don't change it.
• Name — internal admin name.
• Label Text — default storefront text, plus optional per-store-view overrides.
• Background / Text Color — 6-digit hex values.
• Position — top-left, top-right, bottom-left or bottom-right corner of the product image.
• Show on Product Listings / Product Page — per-placement visibility.
• Priority — lower renders first; also decides which labels survive the per-product cap.
• Rule — None (manual only), New products, or On sale (special price below regular price).

Manual assignment

Edit a product → Product Details → Product Labels multiselect. This is the merchandiser's surface; the module never writes this attribute. The attribute is global scope: one manual selection per product across all stores (per-store display text still varies via overrides).

Computed assignment

Set a label's Rule to New products or On sale and the Product Labels indexer materializes matching products per store view:

In Update by Schedule mode (default changelog subscriptions: product entity, product datetime and decimal attribute values) product edits are picked up incrementally by the standard index cron group — no custom cron. Saving a label whose rule or active flag changed invalidates the indexer automatically.

A product's storefront labels are the union of its manual and computed labels, filtered by placement, ordered by priority, and capped by Maximum Labels Per Product.

Honest limitations (Release 1)

• On sale detects special prices only — products discounted purely via catalog price rules are not detected. (Planned for a later release.)
• New products follows the standard Magento news window: at least one of the From/To dates must be set and the window must contain the current store-local time.
• Labels are text badges; image/shape labels are not part of Release 1.
• Cart, mini-cart and checkout placements are not part of Release 1.

GraphQL

magendoo_labels returns the product's active labels for the current store view, ordered by priority and capped by Maximum Labels Per Product; it returns nothing when Enable Labels is off for that store view. Placement flags are not applied — a headless client decides placement itself. The resolver is batched: one preload serves every product in the query.

Extending: custom rule types

Rule matchers are DI-registered. Implement Magendoo\ProductLabels\Model\Indexer\RuleMatcher\MatcherInterface:

and register it under a new rule-type key:

(Release 1 constraint: saving a label with a custom rule type is blocked by validation — the resource model checks the built-in list from Label::getAvailableRuleTypes(), so besides extending the Magendoo\ProductLabels\Model\Label\Source\RuleType dropdown options you currently need a preference on Magendoo\ProductLabels\Model\ResourceModel\Label to accept the new value. Making both honor DI-registered matchers automatically is planned; treat this extension point as developer-level for now.)

When working with a loaded label programmatically, Label::getStoreOverrides() and Label::getTextForStore($storeId) expose the per-store-view text overrides; the storefront resolver applies the same overrides via SQL for batching.

Troubleshooting

• Badges don't show at all — check Enable Labels for the store view, confirm the label is Active and visible for that placement, and flush the full page cache.
• A rule-based label doesn't apply — run bin/magento indexer:reindex magendoo_product_labels and check bin/magento indexer:status; in Update-by-Schedule mode make sure Magento's cron is running.
• A new store view shows no rule-based labels — computed assignments are materialized per store view; run bin/magento indexer:reindex magendoo_product_labels once after creating a store view.
• A label shows on the product page but not in listings — check its Show on Product Listings flag and the Maximum Labels Per Product cap (higher-priority labels win).
• Store-view text override ignored — overrides apply per store view; confirm you added the override for the store view you are browsing, not the website/default scope.

License

OSL-3.0. Copyright (c) Magendoo (https://magendoo.ro).