docs(storefront): use ProductListingCollectSortingEvent for runtime sortings

[Vin Le (vienthuong)]

Summary

The "Create individual sorting at runtime" recipe on the custom sorting guide does not work and has not worked since v6.6.

It tells you to add a ProductSortingEntity to the sortings criteria extension from ProductListingCriteriaEvent, subscribing with priority => 500 "to add your sorting before the default shopware logic applies". That was accurate while the sorting logic lived in ProductListingFeaturesSubscriber, a listener on the same event. Since shopware/shopware@588c40d51c5 removed that subscriber, SortingListingProcessor::prepare() runs before the event is dispatched, so no listener priority can precede it. Following the guide today produces a sorting that appears in the Storefront dropdown but never orders the products — see shopware/shopware#6072.

This updates the section to the new ProductListingCollectSortingEvent, which is dispatched before the requested sorting is resolved:

• subscribe to ProductListingCollectSortingEvent instead, without the priority workaround and without the stale ProductSortingNotFoundException warning
• add the entity via $event->getSortings()->add(...) instead of reading and re-writing the sortings criteria extension
• drop the now-unused ProductSortingCollection import
• note that the event is available since 6.7.15.0, and what the old recipe actually did on earlier versions

Related links

• Adds the event: fix(core): apply product sortings registered at runtime shopware#16213
• Fixes the reported behaviour: Individual sorting at runtime does not distinguish between ascending and descending shopware#6072
• Jira: https://shopware.atlassian.net/browse/NEXT-40220

Checklist

• I reviewed affected links, code samples, and cross-references, including PageRef references where relevant.
• I added or updated redirects in .gitbook.yaml if pages were moved, renamed, or deleted.
• I updated .wordlist.txt (and sorted it) if spellcheck flags new legitimate terms.
• Any required dependent changes in downstream modules have already been merged and published.
• This pull request is ready for review.

Notes

The dependent-changes box is unchecked because shopware/shopware#16213 is still open. Please merge this only once that lands, so the guide does not document an event that does not exist yet.

No page was moved or renamed, so no redirect is needed. No wordlist entry is needed either: the new identifiers appear only inside code spans and code blocks, the same way ProductListingCriteriaEvent did before.

Verified locally with avtodev/markdown-lint:v1.5 against markdown-style-config.yml — no findings.

[shopware-dev-docs-connector]

Developer Docs healthcheck

Status: Completed with success.
Repository: shopware/docs
Commit: c4678bb
Preview: https://developer-documentation-qi1dl0pa0-shopware-frontends.vercel.app
Workflow run: #5096

[github-actions]

📢 Developer Announcement Recommendation

Recommendation: ❌ No Announcement Recommended

No developer announcement signals were detected.

This PR does not appear to introduce developer-facing changes that require a community announcement.

[Copilot]

Pull request overview

Updates the Shopware 6 storefront guide for adding custom product-listing sortings at runtime to use the newer ProductListingCollectSortingEvent, fixing the documented recipe that no longer applies sortings correctly since the sorting resolution now happens before ProductListingCriteriaEvent is dispatched.

Changes:

• Switches the recipe from ProductListingCriteriaEvent (+ priority workaround) to ProductListingCollectSortingEvent.
• Updates the example code to add the sorting via $event->getSortings()->add(...) and removes the unused ProductSortingCollection import.
• Adds a note about availability since Shopware 6.7.15.0 and explains the behavior on earlier versions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Micha Hobert (Isengo1989)]

Thank you for the PR Vin Le (@vienthuong) 👍