BRD-829: Features & attribute key-value map SDK support

[SteponasK]

Summary

• Adds attributeKeyValueMap property to SearchSettingsRequest alongside existing featuresKeyValueMap
• Updates SearchSettingsRequestBuilder with attributeKeyValueMap() builder method
• Updates fromSearchConfiguration() to read attribute_key_value_map from config arrays
• Serializes attribute_key_value_map in JSON output when non-empty

Business Case

Key-value maps enable human-readable facet names (e.g., "Color", "Size") instead of numeric IDs (e.g., "5", "12") for end-users browsing search facets/filters.

Separate maps allow independent optionality:

• Features can have name translation while attributes don't (and vice versa)
• Avoids ID collisions between features and attributes that share the same numeric ID
• Each map is nullable — if absent, the old ID-based behavior is preserved

When maps are populated

• Preset creation (new applications): auto-populated from platform API during first sync
• NOT on preset editing: existing configurations are not retroactively modified
• Filter configuration save: refreshed when admin explicitly saves filter settings

Backwards Compatibility

• New $attributeKeyValueMap parameter defaults to null — all existing callers continue to work
• fromSearchConfiguration() gracefully handles missing attribute_key_value_map key

Test Plan

• Constructor with attributeKeyValueMap
• JSON serialization includes attribute_key_value_map when set
• JSON serialization omits attribute_key_value_map when null/empty
• fromSearchConfiguration extracts attribute_key_value_map
• with*() methods preserve attributeKeyValueMap
• Builder method and reset

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the search experience by enabling the display of human-readable facet names instead of technical IDs. It introduces a mechanism within the SDK to transmit a feature key-value map, which the backend then utilizes to provide localized and user-friendly labels for search facets, improving clarity and usability for end-users.

Highlights

• Feature Facet Name Translation: Implemented SDK support for a features_key_value_map to translate raw feature IDs (e.g., feature_1) into human-readable names (e.g., Size) for facet names in search results.
• SDK Integration: The SDK now passes the features_key_value_map through SearchSettingsRequest to the Go backend, enabling the backend to use this map for translating facet keys in responses and reverse-translating filter parameters.
• Builder Pattern Support: Added a fluent setter featuresKeyValueMap() to SearchSettingsRequestBuilder for easy configuration of the new mapping.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/V2/ValueObjects/SearchSettings/SearchSettingsRequest.php
  • Added a new featuresKeyValueMap property to the constructor, allowing the inclusion of feature ID to display name mappings.
  • Updated the fromSearchConfiguration static method to extract the features_key_value_map from configuration arrays.
  • Modified the jsonSerialize method to include the features_key_value_map in the serialized output when present.
  • Ensured that all with* immutability methods correctly preserve the featuresKeyValueMap property.
• src/V2/ValueObjects/SearchSettings/SearchSettingsRequestBuilder.php
  • Introduced a private featuresKeyValueMap property to store the feature ID to display name map.
  • Added a public featuresKeyValueMap() fluent setter method to set the map.
  • Updated the build() method to pass the featuresKeyValueMap to the SearchSettingsRequest constructor.
  • Modified the reset() method to clear the featuresKeyValueMap property.
• tests/V2/ValueObjects/SearchSettings/SearchSettingsRequestBuilderTest.php
  • Added a new test testBuildWithFeaturesKeyValueMap to verify the correct handling and serialization of the feature key-value map by the builder.
  • Updated testFluentInterfaceReturnsSelf to include the new featuresKeyValueMap() method in the fluent interface check.
• tests/V2/ValueObjects/SearchSettings/SearchSettingsRequestTest.php
  • Added testConstructorWithFeaturesKeyValueMap to confirm the constructor correctly assigns the map.
  • Included testJsonSerializeIncludesFeaturesKeyValueMap to verify the map is serialized to JSON.
  • Added testJsonSerializeOmitsNullFeaturesKeyValueMap and testJsonSerializeOmitsEmptyFeaturesKeyValueMap to ensure null or empty maps are not serialized.
  • Created testFromSearchConfigurationExtractsFeaturesKeyValueMap and testFromSearchConfigurationHandlesMissingFeaturesKeyValueMap to test map extraction from configuration.
  • Added testWithMethodsPreserveFeaturesKeyValueMap to confirm immutability methods retain the map.

Activity

• The pull request was opened by SteponasK to address Jira ticket BRD-829.
• The changes aim to provide SDK support for passing a features_key_value_map to the Go backend.
• Related pull requests include Invertus/brad-search/pull/290 and Invertus/brad-app/pull/375.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds support for features_key_value_map to the search settings, allowing for feature facet name translation. The changes are well-structured, following the existing immutable value object and builder patterns. The new functionality is also thoroughly covered by unit tests. I have one minor suggestion to make the code slightly more concise.

[gemini-code-assist]

For checking if a nullable array property is not null and not empty, you can use the !empty() language construct. It's more concise and idiomatic in PHP, and achieves the same result as the current condition.

        if (!empty($this->featuresKeyValueMap)) {
            $result['features_key_value_map'] = $this->featuresKeyValueMap;
        }

[SteponasK]

@claude review this. IS this correct & has no bugs?

[claude]

Claude finished @SteponasK's task in 1m 10s —— View job

---

Code Review

• Gather context
• Read changed files
• Analyze for correctness and bugs
• Post review feedback

---

Overall: The implementation is correct and has no bugs. The code follows the existing patterns cleanly, and test coverage is thorough. Here's a detailed breakdown:

SearchSettingsRequest.php

Correctness ✅

• Constructor param added as the last optional param — correct since all preceding params already had defaults.
• fromSearchConfiguration() uses null coalescing (?? null) — safe and idiomatic.
• jsonSerialize() correctly omits the field when null or empty (line 127).
• All four with*() methods correctly preserve $this->featuresKeyValueMap as the last positional arg.

Minor: Gemini's !empty() suggestion

The existing check $this->featuresKeyValueMap !== null && count($this->featuresKeyValueMap) > 0 is functionally equivalent to !empty(...) — no actual issue either way.

Missing withFeaturesKeyValueMap() method

The class has withAppId(), withSearchConfig(), withScoringConfig(), and withResponseConfig(), but no withFeaturesKeyValueMap(). This creates a small API asymmetry — callers can't immutably update just the map on an existing request. Whether this is needed depends on usage patterns, but it's worth noting as a potential gap. Fix this →

SearchSettingsRequestBuilder.php

Correctness ✅

• Property declaration, type annotation, fluent setter, build() pass-through, and reset() all implemented correctly.
• build() correctly passes $this->featuresKeyValueMap as the last positional arg to the SearchSettingsRequest constructor.

Tests

Coverage ✅ — all key scenarios are tested:

Test	Coverage
testConstructorWithFeaturesKeyValueMap	Constructor assignment
testJsonSerializeIncludesFeaturesKeyValueMap	Serialization when set
testJsonSerializeOmitsNullFeaturesKeyValueMap	Omission when null
testJsonSerializeOmitsEmptyFeaturesKeyValueMap	Omission when empty array
testFromSearchConfigurationExtractsFeaturesKeyValueMap	Extraction from config array
testFromSearchConfigurationHandlesMissingFeaturesKeyValueMap	Missing key fallback
testWithMethodsPreserveFeaturesKeyValueMap	All with*() methods preserve the map
testBuildWithFeaturesKeyValueMap	Builder → request → serialization flow
testFluentInterfaceReturnsSelf	Fluent interface chain

One minor gap: testResetClearsAllState doesn't explicitly assert that featuresKeyValueMap is null after reset. This is low risk since the existing test structure (expecting an exception on missing appId) only validates the reset happened, not each individual field. Not a bug, just a completeness note.

Summary

The implementation is correct with no bugs. Logic, serialization, immutability, and builder pattern are all properly implemented. The only actionable item is the missing withFeaturesKeyValueMap() if API symmetry is desired — but this is not a correctness issue.