Original PR: #59241
RFC: pfZP8i-cI-p2 -worth checking it first
WOOMOB-713
Documentation PR: woocommerce/woocommerce-rest-api-docs#271

Changes proposed in this Pull Request:

This pull request introduces a new, flexible search mechanism to the WooCommerce Products REST API (GET /wc/v3/products). Instead of expanding search_name_or_sku parameter even further to support global_unique_id, this implementation uses a combination of the existing search parameter and a new search_fields array parameter. This allows clients to specify which fields to search (name, sku, global_unique_id, description, short_description) and supports cross-field matching logic.

The search behavior has been updated to support cross-field matching same way as a search= parameter:

• Tokenized: The search argument is treated as a collection of space-separated tokens.
• Cross-Field Matching: All tokens must be present across any of the specified fields for a product to match. A product matches if all tokens are found distributed across the selected fields.
• Partial Match: A word containing a token is a valid match.

Examples:

• An argument value of blue shirt with search_fields=name will match a product with the name "Casual Blue Shirt" because both tokens exist in the same field (name), but not "Red Shirt".
• scarf 987 with search_fields=name,global_unique_id will match a product with name "Premium Wool Scarf" and GTIN "9876543210" because the tokens can be found across the specified fields.
• quality professionals with search_fields=description,short_description will match a product where "quality" appears in the short description and "professionals" appears in the description.

This new approach takes precedence over all other search-related parameters: search_name_or_sku, search_sku, and sku. If search_fields is present in a request, all others will be ignored for search logic.

This functionality is added to the v3 REST API products endpoint only.

How to test the changes in this Pull Request:

1. Create products with the following details:

   • Product A:
     • Name: Premium Wool Scarf
     • SKU: SCARF-W-PREM
     • GTIN: 9876543210
     • Description: Essential tool for professionals.
     • Short Description: High quality craftsmanship.
   • Product B:
     • Name: Casual Blue Shirt
     • SKU: SHIRT-B-CASUAL
     • GTIN: 1234567890
     • Description: A premium quality winter scarf made from wool.
     • Short Description: Perfect for summer activities.
   • Product C:
     • Name: Red Cotton Tee
     • SKU: TEE-C-RED
     • GTIN: 0000000000

2. Create an application password for your WordPress user in your user profile page from the WP admin area.

3. Test same-field matching: Perform the following request to find "Product B" by searching for tokens that exist in the same field (name).

   curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku,global_unique_id&search_fields=name&search=blue+shirt"

   You should get one result: the "Casual Blue Shirt" product.

4. Test individual field searches: Verify that single tokens work across all fields.

   # Find by name token
   curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku,global_unique_id&search_fields=name&search=scarf"
   
   # Find by SKU token  
   curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku,global_unique_id&search_fields=sku&search=SCARF"
   
   # Find by GTIN token
   curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku,global_unique_id&search_fields=global_unique_id&search=987"
   
   # Find by description token
   curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku,global_unique_id&search_fields=description&search=winter"
   
   # Find by short description token
   curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku,global_unique_id&search_fields=short_description&search=summer"

5. Test cross-field matching: Confirm that tokens can match across different specified fields.

   # This should return results (tokens match across different fields)
   curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku,global_unique_id&search_fields=name,global_unique_id&search=scarf+987"
   
   # Test cross-field matching with content fields
   curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku,global_unique_id&search_fields=description,short_description&search=quality+professionals"

6. Verify precedence: Confirm that search_fields and search override all other search parameters.

   # Overrides search_name_or_sku
   curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku,global_unique_id&search_fields=name&search=blue&search_name_or_sku=scarf"
   
   # Overrides search and search_sku
   curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku,global_unique_id&search_fields=name&search=blue&search=red&search_sku=TEE"

7. Verify regression: Confirm that the older search parameters continue to work as expected when the new one is not present.

   • The following returns the "Casual Blue Shirt" product:

     curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku&search_name_or_sku=blue+shirt"

   • The following returns the "Red Cotton Tee" product:

     curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku&search=red"

   • The following returns the "Premium Wool Scarf" product:

     curl -u <user>:<application_password> "https://localhost/wp-json/wc/v3/products?_fields=name,sku&search_sku=SCARF"

Changelog entry

• Automatically create a changelog entry from the details below.