Search by

willwright / module-category-sorting

will-wright1

Magento 2 category sorting by stock availability, net paid sales value, review rating and customer-specific price.

Package info

github.com/will-wright1/magento-category-sorting

Type:magento2-module

pkg:composer/willwright/module-category-sorting

Statistics

Installs: 21

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.2.0 2026-11-16 11:50 UTC

This package is auto-updated.

Last update: 2026-11-16 11:53:21 UTC


README

A standalone Magento 2 module that adds Recommended as the default category order. Install it through Composer on each project and keep updates in one repository.

Package: willwright/module-category-sorting · Magento module: Willwright_CategorySorting · Licence: MIT.

Ranking

Recommended applies these rules in order, inside the search engine before pagination:

  1. Immediately available stock, then preorder/backorder, then unavailable products.
  2. Net paid product sales value over the last 180 days, highest first.
  3. Approved product review percentage, highest first.
  4. Magento's indexed price for the current customer group and website, highest first.
  5. Product ID, lowest first, to stabilise page boundaries.

Customers can still choose the existing price, name or position orders. Search results and other product blocks keep their normal sorting. Category filters and Magento's out-of-stock visibility rules still apply.

Requirements and supported scope

  • Magento Open Source 2.4.8 or later in the 2.4 series, PHP 8.3 or later within Magento's supported PHP versions.
  • Magento's standard OpenSearch/Elasticsearch category search adapter with either Magento's native fulltext collection or Amasty Shopby's fulltext collection. Other replacement search engines/collections need separate integration testing.
  • Legacy CatalogInventory or Multi Source Inventory (MSI). The module automatically selects the inventory reader from enabled Magento modules. MSI uses the stock assigned to the store's website, aggregated indexed quantities and outstanding reservations, including the default stock and custom stocks. No MSI packages are required for legacy installations. An AvailabilityProviderInterface remains available for custom inventory integrations; see extension points.
  • Magento cron and the stock/search indexers must be running.

Amasty Preorder is optional. When its module is enabled, its index table exists, and the integration setting is enabled, website-specific preorder designations are included. Native Magento backorders work without Amasty.

The module includes no theme overrides, customer records, order data or project credentials. Recommended has a fixed direction; a theme may still display its normal direction arrow. See theme integration.

Install

Run in your Magento project:

composer require willwright/module-category-sorting:^1.2
php bin/magento module:enable Willwright_CategorySorting
php bin/magento setup:upgrade
php bin/magento setup:di:compile

Sorting is disabled by default so you can build the snapshot and search mapping before activating it. Enable snapshot collection, then reindex during your normal maintenance/deployment window:

php bin/magento maintenance:enable
php bin/magento config:set willwright_category_sorting/general/enabled 1
php bin/magento cache:clean config
php bin/magento indexer:reindex cataloginventory_stock willwright_category_sorting catalogsearch_fulltext
php bin/magento cache:clean block_html full_page
php bin/magento maintenance:disable

On MSI installations, run the inventory indexer after cataloginventory_stock and before willwright_category_sorting. The module automatically adds this dependency when the MSI indexer is registered. For example:

php bin/magento indexer:reindex cataloginventory_stock inventory willwright_category_sorting catalogsearch_fulltext

If Amasty Preorder is installed and used, reindex amasty_preorder_product_preorder after stock and before the ranking indexer. The optional indexer is deliberately not a required dependency. A full reindex of catalogsearch_fulltext is required on first installation to create the numeric field mappings; a partial product reindex is insufficient.

Retain your project's normal static-content deployment and external cache-purge steps. Avoid running another index rebuild concurrently. If indexing fails, resolve the error and finish rebuilding before leaving maintenance mode.

Settings are under Stores → Configuration → Catalog → Catalog → Category Sorting. Enablement can be overridden by website or store view. Test-order exclusions and Amasty integration are global settings. If a store already has an explicit disabled override, change that override as well.

The inventory guard accepts legacy inventory and complete MSI setups. A partially enabled MSI setup is rejected on Admin/CLI activation and kept inactive at runtime; its core Inventory, InventoryCatalog, InventorySales, InventoryIndexer, InventoryConfiguration and InventoryReservations modules must be enabled together. Installed but disabled MSI packages and API contracts alone do not block legacy inventory. The guard does not change your inventory configuration.

For an unpublished GitHub package or a local checkout, see development installation.

Upgrade from 1.0.x or 1.1.x

composer require willwright/module-category-sorting:^1.2 --with-dependencies
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:clean config

This release changes Recommended from unit volume to sales value. Run setup:upgrade before rebuilding: value has its own snapshot column and search field, so old unit counts are never interpreted as money. Rebuild the ranking snapshot and the full search index during your deployment window using the sequence above; a partial search reindex cannot create the new mapping. The five-minute refresh also requests a full metrics build on the first run after this upgrade.

Enable Recommended sorting at the appropriate scope if it was previously blocked by MSI. Existing legacy inventory settings continue to work.

Sales and availability rules

  • Sales across all stores and customer groups contribute to each product's total. There is no channel restriction; paid POS, trade and web orders all count.
  • The 180-day window uses the order's original creation timestamp in UTC. Refunds reduce the original contribution; future orders are excluded.
  • Orders must be in processing or complete and fully paid. A rounding tolerance of 0.0001 is allowed; free product lines contribute zero sales value. Unpaid or partially paid orders do not count.
  • Sales value uses historical invoiced product amounts after line discounts, capped to uncancelled quantities. Fully paid POS/orders without invoices use the discounted order-line amount prorated for cancellations. Credit memo product amounts reduce the contribution, including monetary credits without returned units; each line has a floor of zero. Historical monetary fields must be populated by order-import integrations.
  • Value excludes tax and delivery. Magento's discount tax compensation is included when calculating tax-exclusive discounts and refunds. Order-level shipping refunds and goodwill adjustments are not attributed to products.
  • Base-currency amounts are converted to the default-scope base (global reporting) currency using each order's recorded base_to_global_rate. Orders already in that currency use a rate of one. Foreign-base orders with no valid conversion to that currency are excluded rather than adding incomparable monetary amounts; present-day exchange rates are not used.
  • Configurable and fixed-price bundle parents own their revenue; child rows are excluded. Dynamic-price bundle component revenue is assigned to the purchased bundle once. Standalone sales of a variant also contribute to its currently linked configurable parents.
  • Known test order entity IDs, rather than displayed order numbers, can be excluded in configuration. Exclusion changes take effect at the next full metrics refresh.
  • Ratings use Magento's store-specific approved-review aggregate. Unreviewed products have zero rating; configurable parents use their own displayed rating. There is no new-product boost.
  • Availability respects enabled status, website assignment, indexed salability and inherited/product stock settings. MSI reservations reduce immediately available quantity and compensation reservations restore it. Products without backorders become unavailable when their remaining quantity reaches the out-of-stock threshold. Backorders without immediate stock are demoted; a negative threshold permits limited backorders until that limit is reached. Unmanaged stock remains immediately available when indexed as salable. An explicit purchasable Amasty preorder designation also demotes positive-stock products.
  • A configurable parent uses its best purchasable variant, while the parent itself must remain enabled and salable. Bundles and grouped products use their native indexed stock status, plus optional Amasty composite designations.

Refresh and recovery

willwright_category_sorting_nightly refreshes sales, ratings and availability at 02:15 UTC. willwright_category_sorting_availability compares availability every five minutes and retries a full build when metrics are missing or at least 24 hours old. Actual refresh timing depends on Magento cron and stock/preorder index freshness.

Changed products enter a persistent search-publication queue. The refresh publishes their search documents, invalidates category/product caches, then acknowledges them. Failures leave IDs queued for retry. Publication defers while catalog search is invalid or rebuilding. A shared lock prevents module refresh jobs from overlapping. The module writes only its snapshot and Magento indexer/refresh bookkeeping.

Disabled stores skip ranking reads during ordinary search indexing. When no active store has supported, enabled sorting, scheduled/manual module refreshes return before taking a refresh lock, reading freshness flags, querying sales or processing the publication queue. In mixed configurations only enabled stores are built and their queued rows acknowledged; disabled stores retain pending rows for a future re-enable. Follow the manual snapshot/search reindex steps after re-enabling a store.

For a manual full refresh:

php bin/magento indexer:reindex willwright_category_sorting catalogsearch_fulltext
php bin/magento cache:clean block_html full_page

Check Category Sorting and Catalog Search with indexer:status. Pending publication is needs_reindex = 1 in the willwright_category_sorting table, including any Magento table prefix. Ordinary search indexing also reads current availability and ratings.

To restore the project's existing category defaults, disable Use Recommended Category Sorting at the relevant scope and clean config/full-page caches. The snapshot can remain in place.

Development and publication

Source and releases: GitHub. Composer package: Packagist.