Adds caching support via PSR-16 by JasonTheAdams · Pull Request #157 · WordPress/php-ai-client

JasonTheAdams · 2025-12-30T18:27:59Z

Resolves #141

This PR adds optional PSR-16 caching support to the AI Client. When a cache is configured, model metadata from provider APIs (like the list of available models) is stored and reused instead of making repeated API calls. This improves performance and reduces API usage, especially useful in applications that frequently initialize the client or query model availability.

What's new:

AiClient::setCache() and AiClient::getCache() for configuring a PSR-16 cache
psr/simple-cache added as a dependency
AbstractOpenAiCompatibleModelMetadataDirectory now caches /models API responses
Cache keys are unique per provider to prevent data conflicts
MockCache test helper for verifying cache behavior

github-actions · 2025-12-30T18:28:10Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: JasonTheAdams <[email protected]>
Co-authored-by: felixarntz <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

felixarntz

@JasonTheAdams Looks great! A few additional points to consider, but this is close.

felixarntz · 2026-01-02T00:58:58Z

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleModelMetadataDirectory.php

+     */
+    protected function getCacheKey(): string
+    {
+        return 'ai_client_models_' . md5(static::class);


It would be great if we could include the current AI Client version in the cache key. A version update may come with an updated DTO shape at some point, so it's always safest to invalidate all caches upon update. Or there may be a fix in a specific ModelMetadataDirectory implementation.

This was relevant quite a few times while I worked on AI Services, so I suggest we incorporate that here too.

We don't store the current version anywhere in the codebase, but it's easy to do that in a maintainable way. We could have a specific constant somewhere which we replace its value for as part of the release process. It could even be via a simple vibe coded script.

I added an AiClient::VERSION. It seemed like a sensible place to put it since this a client package and that's the main class. How does that sound?

Tentatively resolved in 5ccaee3

felixarntz · 2026-01-02T01:01:41Z

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleModelMetadataDirectory.php

+
+        // Store in cache.
+        if ($cache !== null) {
+            $cache->set($cacheKey, $this->dehydrateModelMetadataMap($modelMetadataMap));


What's the TTL? We'll need a mechanism for the cache to invalidate.

My suggestion is to use a mix of both:

Set a reasonable TTL, e.g. for a couple hours, maybe a day.

Add some public method to invalidate the cache. We could introduce an interface like WithCachedDataInterface that has a single method invalidateCaches() that would invalidate all relevant caches for the class. And our ModelMetadataDirectory implementations for cloud providers could make use of that.

I updated the trait in 3981997 to handle the invalidateCaches() method.

I also set a 1-day TTL. 👍

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleModelMetadataDirectory.php

felixarntz

@JasonTheAdams Almost good to go, only one important architectural consideration.

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleModelMetadataDirectory.php

felixarntz · 2026-01-18T02:37:40Z

@JasonTheAdams Since you're adding the VERSION constant here, I thought it'd be a good idea to document the prepublish requirements, as basic as they are, since now they are becoming slightly less basic. See #172.

(In the future it would be great to automate this, but I think for now this is useful to at least document.)

felixarntz

@JasonTheAdams LGTM, just one thing that I think is worth improving. Please check before merging, feel free to merge after updating, or let me know if you disagree.

felixarntz · 2026-01-19T22:14:30Z

src/Providers/ApiBasedImplementation/AbstractApiBasedModelMetadataDirectory.php

+    protected function getBaseCacheKey(): string
+    {
+        return 'ai_client_' . AiClient::VERSION . '_' . md5(static::class);
    }


Why not put this in the trait? This implementation here does nothing that wouldn't be suitable for the trait itself - it's not tied to this specific class.

I thought about this, but I didn't want to assume that we always need the class on the end of the key. We really only need it here because this is an abstract class. But another class may not want that in the key, which would also also keys to be shared between contexts.

Agreed, it doesn't always need to be like that, but a protected method would still allow changing it. So IMO having this implementation in the trait as "works for ~90% of cases" would still be helpful.

But not a big deal, we can also iterate later, as changing that would not break anything.

feat: adds caching support via PSR-16

53a0784

JasonTheAdams requested a review from felixarntz December 30, 2025 18:27

JasonTheAdams self-assigned this Dec 30, 2025

JasonTheAdams added this to the 0.4.0 milestone Dec 31, 2025

felixarntz reviewed Jan 2, 2026

View reviewed changes

JasonTheAdams added 4 commits January 16, 2026 11:07

Merge branch 'trunk' into caching-support

9b1e48e

feat: adds AiClient version and uses in cache key

5ccaee3

feat: adds cache interface and trait

6d0e4f7

refactor: adds invalidateCaches handling in the trait

3981997

JasonTheAdams requested a review from felixarntz January 16, 2026 23:48

felixarntz reviewed Jan 18, 2026

View reviewed changes

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleModelMetadataDirectory.php Outdated Show resolved Hide resolved

felixarntz mentioned this pull request Jan 18, 2026

Add a prepublish checklist to have the (brief) requirements documented #172

Merged

feat: improves api caching and caching trait

d6b1a6f

JasonTheAdams requested a review from felixarntz January 19, 2026 21:13

felixarntz approved these changes Jan 19, 2026

View reviewed changes

felixarntz merged commit a65b26a into trunk Jan 20, 2026
12 of 13 checks passed

felixarntz deleted the caching-support branch January 20, 2026 01:57

Conversation

JasonTheAdams commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

felixarntz Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

JasonTheAdams Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

felixarntz Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

JasonTheAdams Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

felixarntz commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

felixarntz Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

JasonTheAdams Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

felixarntz Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JasonTheAdams commented Dec 30, 2025 •

edited

Loading

github-actions bot commented Dec 30, 2025 •

edited

Loading

felixarntz commented Jan 18, 2026 •

edited

Loading