Skip to content

feat: version the entity registry cache key - #295

Closed
ManukMinasyan wants to merge 1 commit into
3.xfrom
feat/entity-cache-version
Closed

ManukMinasyan wants to merge 1 commit into
3.xfrom
feat/entity-cache-version

Conversation

@ManukMinasyan

Copy link
Copy Markdown
Member

An app that deploys with zero downtime can now keep each release on its own entity registry cache. Before, the old release kept serving requests after the deploy step that runs custom-fields:clear-cache, so it could cache its registry again. The new release then read that registry for up to the TTL. On a deploy that adds custom fields to a model, or that upgrades this package, the new code ran on the old registry.

What changed

  • EntityConfigurator::cache() takes an optional third argument, version. An empty string counts as no version, so env() on a machine without the variable behaves as before.
  • EntityManager puts the version into the key: custom_fields_entities:<version>:<panel>, or custom_fields_entities:<panel> without one. clearCache() and custom-fields:clear-cache clear the current version's keys.
  • EntityServiceProvider passes the version from the configurator to the manager. It reads it only from EntityConfigurator, so EntityConfigurationInterface is unchanged and custom implementations keep working.
  • Docs (essentials/configuration): the performance section shows a per-deploy version, with Laravel Cloud's LARAVEL_CLOUD_DEPLOY_UUID as the example.

Why this way

A version supplied by the app works on any platform that exposes a release id, and costs nothing when it is left out. The clear command alone cannot close the gap: deploy steps run before the new release takes traffic, while the old one is still serving.

Behavior to know about

  • Entries cached under an earlier version are never read again and expire after the TTL.
  • With no version, behaviour is exactly as in v3.18.
  • No migration, no new config key.

Tests

tests/Feature/EntityRegistryCacheTest.php adds five cases:

  • The registry is stored under the configured version and not under the bare key.
  • A registry cached under another version is ignored, even when it is empty.
  • An empty version keeps the bare key.
  • The clear command removes the current version's key, which the test first confirms exists.
  • The version survives config:cache (var_export and __set_state).

Four of them fail without the change. The empty-version case passes either way, as it should.

Checked

On 426387cb:

  • vendor/bin/pest --parallel: 1138 passed, 3 todo. PHPStan reports no errors; Rector and Pint pass.
  • In an app with four panels, run as a non-local environment against one Redis store: an old release cached an empty registry under its deploy id. The new release, with another id, read the full registry and stored it under its own key. Without a deploy id, the bare key was used.
  • On Laravel Cloud, the runtime sets LARAVEL_CLOUD_DEPLOY_UUID to the id of the deployment serving the request.

EntityConfigurator::cache() takes an optional version that becomes part of the cache key. Passing a value that changes on every deploy keeps a release from reading a registry the previous release cached while it was still serving traffic.
Copilot AI balanced review requested due to automatic review settings November 9, 2026 10:58

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@ManukMinasyan
ManukMinasyan marked this pull request as draft November 9, 2026 11:07
@ManukMinasyan

Copy link
Copy Markdown
Member Author

Closing: a version read from config is empty on hosts that cache config at build time, which is where it was meant to help. Deploys clear the cache with custom-fields:clear-cache instead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants