[Experimental] Render ProductFilterTaxonomy block on the frontend #59589

dinhtungdu · 2025-07-10T10:45:41Z

Submission Review Guidelines:

I have followed the WooCommerce Contributing Guidelines and the WordPress Coding Standards.
I have checked to ensure there aren't other open Pull Requests for the same update/change.
I have reviewed my code for security best practices.
Following the above guidelines will result in quick merges and clear and detailed feedback when appropriate.

Changes proposed in this Pull Request:

This PR implements the frontend rendering functionality for the ProductFilterTaxonomy block including displaying the options and interacting with options.

Closes WOOPLUG-4767
Closes #59131

Screenshots or screen recordings:

No filter	Has filters

How to test the changes in this Pull Request:

Using the WooCommerce Testing Instructions Guide, include your detailed testing instructions:

Add Product Filters block to the Product Catalog template
Add Taxonomy Filter block inside Product Filters block
Configure the block to filter by a specific taxonomy (e.g., product categories, tags, or custom taxonomies)
Enable Product Counts for all filter blocks that have the settings.
Save the template and view it on the frontend
Verify that the taxonomy filter renders correctly with available terms
Test clicking on different taxonomy terms to filter the products
Verify that the URL parameters are updated correctly when filters are applied
Test that the product collection updates to show only products matching the selected taxonomy terms
Verify that term counts are displayed correctly and update when other filters are applied
Test edge cases like empty taxonomies or invalid configurations to ensure proper error handling

Changelog entry

Automatically create a changelog entry from the details below.

This Pull Request does not require a changelog entry. (Comment required below)

Changelog Entry Details

Significance

Patch
Minor
Major

Type

Fix - Fixes an existing bug
Add - Adds functionality
Update - Update existing functionality
Dev - Development related task
Tweak - A minor adjustment to the codebase
Performance - Address performance issues
Enhancement - Improvement to existing functionality

Message

Changelog Entry Comment

Comment

Experimental - Render ProductFilterTaxonomy block on the frontend frontend

github-actions · 2025-07-11T02:23:49Z

Testing Guidelines

Hi @ralucaStan ,

Apart from reviewing the code changes, please make sure to review the testing instructions (Guide) and verify that relevant tests (E2E, Unit, Integration, etc.) have been added or updated as needed.

Reminder: PR reviewers are required to document testing performed. This includes:

🖼️ Screenshots or screen recordings.
📝 List of functionality tested / steps followed.
🌐 Site details (environment attributes such as hosting type, plugins, theme, store size, store age, and relevant settings).
🔍 Any analysis performed, such as assessing potential impacts on environment attributes and other plugins, conducting performance profiling, or using LLM/AI-based analysis.

⚠️ Within the testing details you provide, please ensure that no sensitive information (such as API keys, passwords, user data, etc.) is included in this public issue.

github-actions · 2025-07-11T02:30:06Z

Size Change: +72 B (0%)

Total Size: 5.91 MB

_{compressed-size-action}

github-actions · 2025-07-11T02:30:59Z

Test using WordPress Playground

The changes in this pull request can be previewed and tested using a WordPress Playground instance.
WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Test this pull request with WordPress Playground.

Note that this URL is valid for 30 days from when this comment was last updated. You can update it by closing/reopening the PR or pushing a new commit.

kmanijak

I tested the PR and found interesting case, where I could only add:

Brands Filter
Tags Filter
but no Categories Filter.

Inserter	Inspector Controls

After syncing with @dinhtungdu to debug, we found out there's a bug in get_taxonomies function. They're being queried by 'object_type' => array( 'product' ), but plugins may change/extend the object_type and as an example, I had Product Add Ons plugin activated, which resulted in product_cat object_type being an array:

       [object_type] => Array
                (
                    [0] => product
                    [1] => global_product_addon
                )

and filters out product_cat from query.

Anyway, I tested the PR after disabling the plugin and I consider the above issue a separate one (to be addressed in separate PR) hence pre-approving! ✅

Tested:

Filters display correct data in both: list and chips
Filters can be mixed with each other
Filters display correct amount of products

Minor issue I found is incorrect char decoding, & is correctly displayed in filter chips but incorrectly in Active Filters

Chip	Active Filter

kmanijak · 2025-07-11T10:22:09Z

plugins/woocommerce/src/Blocks/BlockTypes/ProductFilterTaxonomy.php

+	 * @param WP_Block $block            Block instance.
+	 * @return string Rendered block type output.
+	 */
+	protected function render( $block_attributes, $content, $block ) {


A lot is happening in render method and it takes time to get it. I appreciate the comments before each section but would you consider splitting it into methods? Not a must but from a reviewer perspective (or later someone who's gonna read this) it may be easier to digest the content. 😄

I don't consider it a must, especially that it's WIP and you may be still evolving this class so it's up to you as you know the context and plans 🙌

dinhtungdu · 2025-07-16T15:33:04Z

@kmanijak I fixed the issue with the taxonomy query, we should have correct taxonomies now with any extension activated.

About the encoding issue, it's an issue with Active filter data, so I will address that in a follow-up.

About splitting the big render function, as I talked in our sync, for now, I prefer the big method over splitting it into multiple private methods, which are used only once. You can go through the whole method in one go and understand what it's doing instead of jumping back and forth between smaller methods. It may change along the way, but for now, let's keep this big boy.

- Add get_taxonomy_term_counts method with FilterData integration - Include necessary imports for ProductCollectionUtils and FilterData classes - Add circular counting prevention for attribute filters - Add placeholder render method for future implementation

- Add full frontend rendering logic similar to ProductFilterAttribute - Handle taxonomy validation and term retrieval with proper ordering/sorting - Implement selected term detection from filter parameters - Build filter context and options for inner blocks - Add interactive wrapper attributes for frontend filtering - Handle empty state with proper hiding - Include proper error handling and early exit conditions - All linting issues resolved

- Validate taxonomy exists in parameter map before expensive operations - Prevents unnecessary term counting when taxonomy not configured - Removes duplicate container/params_handler initialization - Improves performance by failing fast on invalid configurations

- Handle taxonomy filter type in frontend.ts parameter building - Add URL parameter mapping for taxonomy filters using filter_taxonomy format - Include TODO note for future refactoring to use centralized Params class - Enables frontend interaction for ProductFilterTaxonomy blocks

Replace hardcoded filter_taxonomy format with centralized parameter mapping from Params class. This ensures consistent URL parameter generation across the system and allows for custom taxonomy parameter names like 'categories' for product_cat.

coderabbitai · 2025-07-22T02:59:30Z

📝 Walkthrough

Walkthrough

This change updates the WooCommerce Product Filters functionality by enhancing taxonomy filter handling. The frontend logic now dynamically maps taxonomy filter parameters, while the backend ProductFilterTaxonomy block class is refactored to centralize parameter mapping, optimize term count queries, and improve selected filter preparation and rendering.

Changes

File(s)	Change Summary
plugins/woocommerce/client/blocks/assets/js/blocks/product-filters/frontend.ts	Updated the `params` getter logic to handle taxonomy filters by extracting taxonomy names, using a config-based parameter mapping, and assigning filter values under the correct parameter key. Added a comment for future refactoring.
plugins/woocommerce/src/Blocks/BlockTypes/ProductFilterTaxonomy.php	Refactored and enhanced the block class: added `initialize()` to hook into filter preparation, introduced `prepare_selected_filters()` for active taxonomy filter processing, added a `render()` method for frontend rendering with accurate term counts and context, added `get_taxonomy_term_counts()` helper, and updated `get_taxonomies()` for mapping.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Frontend (JS)
    participant Backend (PHP Block)
    participant WooCommerce Data Providers

    User->>Frontend (JS): Selects taxonomy filter
    Frontend (JS)->>Frontend (JS): Map taxonomy filter to param key via config
    Frontend (JS)->>Backend (PHP Block): Request filtered products with taxonomy params
    Backend (PHP Block)->>Backend (PHP Block): prepare_selected_filters() processes params
    Backend (PHP Block)->>WooCommerce Data Providers: get_taxonomy_term_counts()
    WooCommerce Data Providers-->>Backend (PHP Block): Return term counts
    Backend (PHP Block)->>Frontend (JS): Render block with filter context and counts

Estimated code review effort

4 (~75 minutes)

Possibly related PRs

Product Filters: Add get_taxonomy_counts method to FilterData class #59462: Adds get_taxonomy_counts method in FilterData, complementing this PR's taxonomy count handling for filters.
Add taxonomy support to Product Collection Data API endpoint #59608: Adds API support for taxonomy counts in product collection data, related to taxonomy filtering but not directly overlapping in code.

📜 Recent review details

Configuration used: .coderabbit.yml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 588c5e6 and de38fef.

📒 Files selected for processing (1)

plugins/woocommerce/src/Blocks/BlockTypes/ProductFilterTaxonomy.php (3 hunks)

📓 Path-based instructions (2)

**/*.{php,js,jsx,ts,tsx}

📄 CodeRabbit Inference Engine (.cursor/rules/code-quality.mdc)

**/*.{php,js,jsx,ts,tsx}: Guard against unexpected inputs
Sanitize and validate any potentially dangerous inputs
Ensure code is backwards compatible
Write code that is readable and intuitive
Ensure code has unit or E2E tests where applicable

Files:

plugins/woocommerce/src/Blocks/BlockTypes/ProductFilterTaxonomy.php

**/*.{php,js,ts,jsx,tsx}

⚙️ CodeRabbit Configuration File

**/*.{php,js,ts,jsx,tsx}: Don't trust that extension developers will follow the best practices, make sure the code:

Guards against unexpected inputs.

Sanitizes and validates any potentially dangerous inputs.

Is backwards compatible.

Is readable and intuitive.

Has unit or E2E tests where applicable.

Files:

plugins/woocommerce/src/Blocks/BlockTypes/ProductFilterTaxonomy.php

🧠 Learnings (2)

📓 Common learnings

Learnt from: samueljseay
PR: woocommerce/woocommerce#59051
File: plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/mini-cart-contents/inner-blocks/mini-cart-footer-block/index.tsx:66-70
Timestamp: 2025-06-23T05:47:52.696Z
Learning: For WooCommerce mini-cart blocks in plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/, the standardized conditional pattern for experimental features should be `if ( isExperimentalMiniCartEnabled() ) { blockSettings.save = () => <InnerBlocks.Content />; }` - defaulting to the traditional Save component and only overriding when the experimental feature is enabled.

Learnt from: samueljseay
PR: woocommerce/woocommerce#58716
File: plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/iapi-frontend.ts:83-101
Timestamp: 2025-06-17T07:07:53.443Z
Learning: In WooCommerce blocks, when porting existing code patterns that have known issues (like parseInt truncating decimal money values), maintain consistency with existing implementation rather than making isolated fixes. The preference is for systematic refactoring approaches (like broader Dinero adoption) over piecemeal changes.

Learnt from: CR
PR: woocommerce/woocommerce#0
File: .cursor/rules/generate-pr-description.mdc:0-0
Timestamp: 2025-07-21T05:22:46.417Z
Learning: Provide clear, step-by-step instructions for how to test the changes in the PR description.

Learnt from: dinhtungdu
PR: woocommerce/woocommerce#59499
File: plugins/woocommerce/src/Internal/ProductFilters/QueryClauses.php:327-332
Timestamp: 2025-07-10T04:22:27.648Z
Learning: In the WooCommerce ProductFilters QueryClauses class, the $chosen_taxonomies parameter in add_taxonomy_clauses() already contains only validated public product taxonomies. The validation occurs upstream in the Params class during parameter registration, so additional taxonomy existence validation in the processing methods is redundant.

Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.

Learnt from: ralucaStan
PR: woocommerce/woocommerce#58782
File: plugins/woocommerce/client/blocks/assets/js/base/utils/render-frontend.tsx:0-0
Timestamp: 2025-06-16T16:12:12.148Z
Learning: For WooCommerce checkout blocks, lazy loading was removed in favor of direct imports to prevent sequential "popping" effects during component loading. This approach prioritizes user experience over code splitting, with minimal bundle size impact and improved performance (1.7s to 1.1s speed score improvement). The checkout flow benefits from having all components load together rather than incrementally.

Learnt from: vladolaru
PR: woocommerce/woocommerce#58784
File: plugins/woocommerce/src/Internal/Admin/Settings/PaymentsProviders/Paytrail.php:29-35
Timestamp: 2025-06-18T09:58:10.616Z
Learning: In WooCommerce codebase, prefer using `wc_string_to_bool()` over `filter_var($value, FILTER_VALIDATE_BOOLEAN)` when converting option values (especially 'yes'/'no' style flags) to boolean. The WooCommerce helper function is more idiomatic and handles the conversion consistently with core WooCommerce patterns.

Learnt from: Aljullu
PR: woocommerce/woocommerce#58809
File: plugins/woocommerce/src/Blocks/BlockTypes/ProductButton.php:222-225
Timestamp: 2025-06-13T17:11:13.732Z
Learning: In `plugins/woocommerce/src/Blocks/BlockTypes/ProductButton.php`, the team intentionally relies on toggling the `disabled` CSS class (via `data-wp-class--disabled`) instead of binding the `disabled` attribute, to mirror the behavior of the classic WooCommerce template.

plugins/woocommerce/src/Blocks/BlockTypes/ProductFilterTaxonomy.php (8)

Learnt from: dinhtungdu
PR: #59499
File: plugins/woocommerce/src/Internal/ProductFilters/QueryClauses.php:327-332
Timestamp: 2025-07-10T04:22:27.648Z
Learning: In the WooCommerce ProductFilters QueryClauses class, the $chosen_taxonomies parameter in add_taxonomy_clauses() already contains only validated public product taxonomies. The validation occurs upstream in the Params class during parameter registration, so additional taxonomy existence validation in the processing methods is redundant.

Learnt from: samueljseay
PR: #58716
File: plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/iapi-frontend.ts:83-101
Timestamp: 2025-06-17T07:07:53.443Z
Learning: In WooCommerce blocks, when porting existing code patterns that have known issues (like parseInt truncating decimal money values), maintain consistency with existing implementation rather than making isolated fixes. The preference is for systematic refactoring approaches (like broader Dinero adoption) over piecemeal changes.

Learnt from: gigitux
PR: #58902
File: plugins/woocommerce/client/blocks/assets/js/blocks/product-specifications/edit.tsx:205-206
Timestamp: 2025-06-17T12:40:54.118Z
Learning: In WordPress blocks, when there's a styling mismatch between editor and frontend, check if the PHP renderer (like in ProductSpecifications.php) adds specific classes to the output. If so, add those same classes to the useBlockProps className in the editor component (like in edit.tsx) to ensure consistent styling. For example, adding wp-block-table class to both frontend and editor ensures core table styles and theme customizations apply consistently.

Learnt from: Aljullu
PR: #58809
File: plugins/woocommerce/src/Blocks/BlockTypes/ProductButton.php:222-225
Timestamp: 2025-06-13T17:11:13.732Z
Learning: In plugins/woocommerce/src/Blocks/BlockTypes/ProductButton.php, the team intentionally relies on toggling the disabled CSS class (via data-wp-class--disabled) instead of binding the disabled attribute, to mirror the behavior of the classic WooCommerce template.

Learnt from: senadir
PR: #59426
File: plugins/woocommerce/client/legacy/js/frontend/a8c-address-autocomplete-service.js:355-355
Timestamp: 2025-07-08T09:14:47.894Z
Learning: In the WooCommerce address autocomplete system, input sanitization happens upstream in address-autocomplete.js before data reaches a8c-address-autocomplete-service.js. The trim() operation in the service file is for optimization purposes (to skip API requests when only spaces are added), not for security sanitization.

Learnt from: CR
PR: woocommerce/woocommerce#0
File: .cursor/rules/code-quality.mdc:0-0
Timestamp: 2025-07-18T14:54:36.232Z
Learning: Applies to **/*.{php,js,jsx,ts,tsx} : Sanitize and validate any potentially dangerous inputs

Learnt from: vladolaru
PR: #58784
File: plugins/woocommerce/src/Internal/Admin/Settings/PaymentsProviders/Paytrail.php:29-35
Timestamp: 2025-06-18T09:58:10.616Z
Learning: In WooCommerce codebase, prefer using wc_string_to_bool() over filter_var($value, FILTER_VALIDATE_BOOLEAN) when converting option values (especially 'yes'/'no' style flags) to boolean. The WooCommerce helper function is more idiomatic and handles the conversion consistently with core WooCommerce patterns.

Learnt from: samueljseay
PR: #59142
File: plugins/woocommerce/src/Blocks/BlockTypes/MiniCart.php:594-602
Timestamp: 2025-06-25T06:51:41.381Z
Learning: WooCommerce block templates have a predictable structure where each block has one top-level div with wp-block-woocommerce- class containing arbitrary nested content that should be preserved.

🪛 PHPMD (2.15.0)

plugins/woocommerce/src/Blocks/BlockTypes/ProductFilterTaxonomy.php

115-115: Avoid unused parameters such as '$content'. (Unused Code Rules)

(UnusedFormalParameter)

🧰 Additional context used

📓 Path-based instructions (2)

**/*.{php,js,jsx,ts,tsx}

📄 CodeRabbit Inference Engine (.cursor/rules/code-quality.mdc)

**/*.{php,js,jsx,ts,tsx}: Guard against unexpected inputs
Sanitize and validate any potentially dangerous inputs
Ensure code is backwards compatible
Write code that is readable and intuitive
Ensure code has unit or E2E tests where applicable

Files:

plugins/woocommerce/src/Blocks/BlockTypes/ProductFilterTaxonomy.php

**/*.{php,js,ts,jsx,tsx}

⚙️ CodeRabbit Configuration File

**/*.{php,js,ts,jsx,tsx}: Don't trust that extension developers will follow the best practices, make sure the code:

Guards against unexpected inputs.

Sanitizes and validates any potentially dangerous inputs.

Is backwards compatible.

Is readable and intuitive.

Has unit or E2E tests where applicable.

Files:

plugins/woocommerce/src/Blocks/BlockTypes/ProductFilterTaxonomy.php

🧠 Learnings (2)

📓 Common learnings

Learnt from: samueljseay
PR: woocommerce/woocommerce#59051
File: plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/mini-cart-contents/inner-blocks/mini-cart-footer-block/index.tsx:66-70
Timestamp: 2025-06-23T05:47:52.696Z
Learning: For WooCommerce mini-cart blocks in plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/, the standardized conditional pattern for experimental features should be `if ( isExperimentalMiniCartEnabled() ) { blockSettings.save = () => <InnerBlocks.Content />; }` - defaulting to the traditional Save component and only overriding when the experimental feature is enabled.

Learnt from: samueljseay
PR: woocommerce/woocommerce#58716
File: plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/iapi-frontend.ts:83-101
Timestamp: 2025-06-17T07:07:53.443Z
Learning: In WooCommerce blocks, when porting existing code patterns that have known issues (like parseInt truncating decimal money values), maintain consistency with existing implementation rather than making isolated fixes. The preference is for systematic refactoring approaches (like broader Dinero adoption) over piecemeal changes.

Learnt from: CR
PR: woocommerce/woocommerce#0
File: .cursor/rules/generate-pr-description.mdc:0-0
Timestamp: 2025-07-21T05:22:46.417Z
Learning: Provide clear, step-by-step instructions for how to test the changes in the PR description.

Learnt from: dinhtungdu
PR: woocommerce/woocommerce#59499
File: plugins/woocommerce/src/Internal/ProductFilters/QueryClauses.php:327-332
Timestamp: 2025-07-10T04:22:27.648Z
Learning: In the WooCommerce ProductFilters QueryClauses class, the $chosen_taxonomies parameter in add_taxonomy_clauses() already contains only validated public product taxonomies. The validation occurs upstream in the Params class during parameter registration, so additional taxonomy existence validation in the processing methods is redundant.

Learnt from: jorgeatorres
PR: woocommerce/woocommerce#59675
File: .github/workflows/release-bump-as-requirement.yml:48-65
Timestamp: 2025-07-15T15:39:21.856Z
Learning: In WooCommerce core repository, changelog entries for all PRs live in `plugins/woocommerce/changelog/` directory and are processed during releases, not at the repository root level.

Learnt from: ralucaStan
PR: woocommerce/woocommerce#58782
File: plugins/woocommerce/client/blocks/assets/js/base/utils/render-frontend.tsx:0-0
Timestamp: 2025-06-16T16:12:12.148Z
Learning: For WooCommerce checkout blocks, lazy loading was removed in favor of direct imports to prevent sequential "popping" effects during component loading. This approach prioritizes user experience over code splitting, with minimal bundle size impact and improved performance (1.7s to 1.1s speed score improvement). The checkout flow benefits from having all components load together rather than incrementally.

Learnt from: vladolaru
PR: woocommerce/woocommerce#58784
File: plugins/woocommerce/src/Internal/Admin/Settings/PaymentsProviders/Paytrail.php:29-35
Timestamp: 2025-06-18T09:58:10.616Z
Learning: In WooCommerce codebase, prefer using `wc_string_to_bool()` over `filter_var($value, FILTER_VALIDATE_BOOLEAN)` when converting option values (especially 'yes'/'no' style flags) to boolean. The WooCommerce helper function is more idiomatic and handles the conversion consistently with core WooCommerce patterns.

Learnt from: Aljullu
PR: woocommerce/woocommerce#58809
File: plugins/woocommerce/src/Blocks/BlockTypes/ProductButton.php:222-225
Timestamp: 2025-06-13T17:11:13.732Z
Learning: In `plugins/woocommerce/src/Blocks/BlockTypes/ProductButton.php`, the team intentionally relies on toggling the `disabled` CSS class (via `data-wp-class--disabled`) instead of binding the `disabled` attribute, to mirror the behavior of the classic WooCommerce template.