README

Rule-driven categories for Magento 2.

Flag a category as smart, describe its products with a rule such as Price greater than 100 AND Color is Blue, and the module keeps the category's product list in line with that rule. Products are added when they start to match and removed when they stop.

What it does
User guides
Requirements
Installation
Quick start
Configuration
How it works
Known limitations
Testing

What it does

Adds a Smart Rules section to the category form in admin, with the same condition builder used by the Products List widget.
Assigns matching products to the category and removes the rest. Products added by hand to a smart category are removed unless they match the rule.
Updates in the background. Saving a category or product queues the work, so saves stay fast.
Runs a full check of every smart category each night, to catch changes made by imports or bulk updates.
Provides a command to recompute on demand.

Categories that are not smart are never touched. A smart category with no conditions is emptied, not filled with the whole catalogue.

User guides

Guide	For	Covers
Creating a smart category	Merchandisers	Switching smart rules on, building a rule, checking the result
Managing smart categories	Merchandisers	When categories update, editing and turning off rules, what shoppers see
Configuration	Administrators and developers	Settings, permissions, queue consumers, the recompute command
Troubleshooting	Everyone	Categories that do not update, missing products, count differences, logs

Requirements

Magento 2 or Mage-OS, PHP 8.1 to 8.4 (tested on Mage-OS 3.5.0, PHP 8.4)
Magento_PageBuilder enabled
Cron running

Installation

Composer

composer require upturnstudio/module-smart-categories
bin/magento module:enable UpturnStudio_SmartCategories
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Manual

Copy the module to app/code/UpturnStudio/SmartCategories, then run:

bin/magento module:enable UpturnStudio_SmartCategories
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Quick start

Go to Catalog → Categories and open a category.
Open Smart Rules and switch Enable smart rules on.
Click +, choose an attribute, then set the operator and value. Use ALL or ANY to combine several conditions.
Save.

The category updates once the queue has run. With cron running this happens on its own. To apply a rule straight away:

# One category
bin/magento upturnstudio:smart-categories:recompute --category-id=42

# Every smart category
bin/magento upturnstudio:smart-categories:recompute

The full walkthrough is in Creating a smart category.

Configuration

Stores → Configuration → UpturnStudio → Smart Categories

Setting	Default	Purpose
Enable Recompute	Yes	Master switch for updates on save, from the queue and from the nightly run. The recompute command ignores it.
Reconcile Batch Size	500	Reserved. Not used by the current version.
Cron Schedule	`0 3 * * *`	When the nightly full check runs.

See Configuration for permissions and queue details.

How it works

Trigger	Path	Result
Smart category saved	`catalog_category_save_commit_after` → queue `upturnstudio_smartcategories.category_recompute`	Category fully reconciled against its rule
Product saved	`catalog_product_save_commit_after` → queue `upturnstudio_smartcategories.product_evaluate`	Product checked against every smart category
Nightly cron	`upturnstudio_smartcategories_full_reconcile`	Every smart category fully reconciled
CLI	`upturnstudio:smart-categories:recompute`	One or every smart category fully reconciled

The rule is stored as JSON in the smart_conditions category attribute, and the toggle in smart_is_enabled. Both are global scope.
Membership is written to catalog_category_product, so the storefront, layered navigation and other modules see a smart category as a normal one.
Affected products are reindexed in the category/product indexers unless those are set to "Update by Schedule".

Known limitations

ANY rules can miss products. A product with no value for one of the attributes in an ANY rule is left out, even when it matches another condition. ALL rules are not affected.
Hidden and disabled products are assigned. Products set to "Not Visible Individually" can match a rule, so the product count in admin can be higher than on the storefront.
Default store values only. Rules ignore store view overrides.
Storefront can lag behind admin. When indexers are set to "Update by Schedule", the storefront changes on the next indexer cron run.

Testing

vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist app/code/UpturnStudio/SmartCategories/Test/Unit

Manual test cases and the latest results are in docs/qa-test-results.md.

upturnstudio / module-smart-categories

Package info

Security

Statistics