[wp-trac] [WordPress Trac] #65127: Introduce 'wp_ai_client_cache_group' filter to allow customization of the object cache group

[WordPress Trac]

#65127: Introduce 'wp_ai_client_cache_group' filter to allow customization of the
object cache group
--------------------------------+-----------------------------
 Reporter:  baikare.sandeep007  |      Owner:  (none)
     Type:  enhancement         |     Status:  new
 Priority:  normal              |  Milestone:  Awaiting Review
Component:  AI                  |    Version:  trunk
 Severity:  normal              |   Keywords:  has-patch
  Focuses:  administration      |
--------------------------------+-----------------------------
 = Introduce 'wp_ai_client_cache_group' filter to allow customization of
 the object cache group =

 == Description

 This patch introduces a new filter, `wp_ai_client_cache_group`, to the
 `WP_AI_Client_Cache` class. This allows developers and integrators to
 change the object-cache group under which the AI client stores its keys.

 Previously, the cache group was hardcoded as the class constant
 `self::CACHE_GROUP` (`'wp_ai_client'`). This patch replaces all direct
 references to the constant with a call to a new private method
 `get_cache_group()`, which applies the new filter.

 == Purpose

 The `wp_ai_client_cache_group` filter provides integrators with greater
 control over cache placement and invalidation. Key benefits include:

 === 1. Avoid Key Collisions
 Plugins or themes can choose a distinct group to avoid clashing with other
 code that might use similar cache keys on the same site.

 === 2. Environment-Specific Caches
 On multisite or hosting platforms that namespace caches per-site,
 integrators can map AI client keys into a per-site or per-environment
 group (e.g., include the blog ID or environment name) to prevent cross-
 site data leakage.

 === 3. Backend Constraints / Compatibility
 Some persistent object cache implementations treat groups differently (or
 do not support group flushing). Allowing the group to be replaced lets
 integrators adapt—for example, to use a group the host supports or to fall
 back to transient-based storage.

 === 4. Testing and Isolation
 Unit and integration tests can switch the cache group to an ephemeral one
 (or a mock group) so test runs do not interfere with real cached data.

 === 5. Targeted Invalidation / Performance
 Integrators who want to implement custom invalidation strategies—such as
 namespacing by model/version or sharding keys—can change the group to a
 name that their backend can efficiently flush or monitor.

 == Implementation Notes

 * A new private method `get_cache_group(): string` is introduced. This
 method applies the `wp_ai_client_cache_group` filter to the default
 `self::CACHE_GROUP` constant.
 * All cache operations (`wp_cache_get`, `wp_cache_set`, `wp_cache_delete`,
 etc.) now use `$this->get_cache_group()` instead of the hardcoded
 constant.
 * The filter is expected to return a **string** cache group name. For
 predictable behavior, the returned value is explicitly cast to a string.
 * Two new unit tests are added to `Tests_AI_Client_Cache`:
     1. `test_cache_group_filter_is_respected`: Verifies the filter changes
 the group used for cache operations.
     2. `test_cache_group_filter_returns_non_string`: Confirms non-string
 filter return values are properly cast to strings.

 == Example Usage

 === Basic: Change to a custom group
 {{{#!php
 <?php
 add_filter( 'wp_ai_client_cache_group', function( $group ) {
     return 'my_plugin_ai_cache';
 } );
 }}}
 This stores all AI client cache items under the `'my_plugin_ai_cache'`
 group.

 === Multisite: Per-site isolation
 {{{#!php
 <?php
 add_filter( 'wp_ai_client_cache_group', function( $group ) {
     return $group . '_site_' . get_current_blog_id();
 } );
 }}}
 This appends the current site ID to the cache group, preventing cross-site
 cache sharing.

 === Testing: Use an ephemeral group
 {{{#!php
 <?php
 add_filter( 'wp_ai_client_cache_group', function( $group ) {
     return 'tests_' . uniqid();
 } );
 }}}
 This generates a unique, temporary cache group for the duration of a test
 run.

 == Backward Compatibility

 * **Fully backward compatible** – When the filter is not used, the cache
 group defaults to the original `'wp_ai_client'` constant, preserving
 existing behavior.
 * **No functional changes** to existing code that relies on the hardcoded
 cache group.

 == Impact

 * **Performance:** Negligible overhead – the filter only executes on cache
 operations and the method is lightweight.
 * **Security:** None – this is an additive change that provides more
 control without introducing new attack surfaces.

 == Testing

 The attached patch includes comprehensive unit test coverage:
 1. Verifies that applying the filter changes the cache group used for
 `set()` and `get()` operations.
 2. Ensures that non-string return values (e.g., integers) are gracefully
 cast to strings.

 Manual testing has confirmed that existing cache functionality remains
 unchanged when the filter is not applied.

 == Props

 Props @baikare.sandeep007.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/65127>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform