From 426387cb42748d2e7e51ba1961b8a3fec4825523 Mon Sep 17 00:00:00 2001 From: Manuk Date: Mon, 9 Nov 2026 14:57:09 +0400 Subject: [PATCH] feat: version the entity registry cache key 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. --- docs/content/2.essentials/1.configuration.md | 12 ++++- src/EntitySystem/EntityConfigurator.php | 10 +++- src/EntitySystem/EntityManager.php | 3 +- src/Providers/EntityServiceProvider.php | 3 ++ tests/Feature/EntityRegistryCacheTest.php | 51 +++++++++++++++++++- 5 files changed, 74 insertions(+), 5 deletions(-) diff --git a/docs/content/2.essentials/1.configuration.md b/docs/content/2.essentials/1.configuration.md index 8e03b05c..a4b65d86 100644 --- a/docs/content/2.essentials/1.configuration.md +++ b/docs/content/2.essentials/1.configuration.md @@ -303,7 +303,17 @@ Optimize for production: ->cache(enabled: true, ttl: 3600), // Cache field types ``` -The entity registry is cached once per Filament panel, because discovery reads each panel's own resources. Clear it on every deploy so a changed `entity_configuration` takes effect at once. The command clears the entity registry only: +The entity registry is cached once per Filament panel, because discovery reads each panel's own resources. + +During a zero-downtime deploy the old release keeps serving requests for a while, and it can cache its registry for the new release to read. Pass a value that changes on every deploy as the cache version, so each release reads only what it cached itself: + +```php +'entity_configuration' => EntityConfigurator::configure() + ->discover(app_path('Models')) + ->cache(true, ttl: 3600, version: env('LARAVEL_CLOUD_DEPLOY_UUID')), // or your platform's release id +``` + +Entries cached under an earlier version expire after the TTL. Without a version, clear the registry on every deploy instead. The command clears the entity registry only: ```bash php artisan custom-fields:clear-cache diff --git a/src/EntitySystem/EntityConfigurator.php b/src/EntitySystem/EntityConfigurator.php index 6a510575..d7e87d2c 100644 --- a/src/EntitySystem/EntityConfigurator.php +++ b/src/EntitySystem/EntityConfigurator.php @@ -26,6 +26,8 @@ final class EntityConfigurator implements EntityConfigurationInterface private int $cacheTtl = 3600; + private ?string $cacheVersion = null; + private array $entityModels = []; private function __construct() @@ -107,10 +109,11 @@ public function exclude(array $models): self /** * Configure caching for entity discovery */ - public function cache(bool $enabled = true, int $ttl = 3600): self + public function cache(bool $enabled = true, int $ttl = 3600, ?string $version = null): self { $this->cacheEnabled = $enabled; $this->cacheTtl = max(60, $ttl); // Minimum 1 minute cache + $this->cacheVersion = $version === '' ? null : $version; return $this; } @@ -211,6 +214,11 @@ public function getCacheTtl(): int return $this->cacheTtl; } + public function getCacheVersion(): ?string + { + return $this->cacheVersion; + } + /** * Get entities array */ diff --git a/src/EntitySystem/EntityManager.php b/src/EntitySystem/EntityManager.php index 353662d8..67980b7f 100644 --- a/src/EntitySystem/EntityManager.php +++ b/src/EntitySystem/EntityManager.php @@ -39,6 +39,7 @@ final class EntityManager implements EntityManagerInterface public function __construct( private readonly bool $cacheEnabled = true, private readonly int $cacheTtl = 3600, + private readonly ?string $cacheVersion = null, ) {} /** @@ -135,7 +136,7 @@ public function clearCache(): static // Discovery reads the current panel's resources, so each panel caches its own registry. private function cacheKey(string $panelId): string { - return self::CACHE_KEY.':'.$panelId; + return implode(':', array_filter([self::CACHE_KEY, $this->cacheVersion, $panelId])); } private function currentPanelId(): string diff --git a/src/Providers/EntityServiceProvider.php b/src/Providers/EntityServiceProvider.php index 7eca2fb9..e50bd034 100644 --- a/src/Providers/EntityServiceProvider.php +++ b/src/Providers/EntityServiceProvider.php @@ -8,6 +8,7 @@ use Relaticle\CustomFields\Contracts\EntityConfigurationInterface; use Relaticle\CustomFields\Contracts\EntityManagerInterface; use Relaticle\CustomFields\Data\EntityConfigurationData; +use Relaticle\CustomFields\EntitySystem\EntityConfigurator; use Relaticle\CustomFields\EntitySystem\EntityManager; use Relaticle\CustomFields\Enums\EntityFeature; @@ -26,6 +27,7 @@ public function register(): void return new EntityManager( cacheEnabled: $config['cache_entities'] ?? true, cacheTtl: $config['cache_ttl'] ?? 3600, + cacheVersion: $config['cache_version'] ?? null, ); }); @@ -140,6 +142,7 @@ private function getEntityConfig(): array 'excluded_models' => $entityConfiguration->getExcludedModels(), 'cache_entities' => $entityConfiguration->getCacheEnabled(), 'cache_ttl' => $entityConfiguration->getCacheTtl(), + 'cache_version' => $entityConfiguration instanceof EntityConfigurator ? $entityConfiguration->getCacheVersion() : null, 'entities' => $entityConfiguration->getEntities(), ]; } diff --git a/tests/Feature/EntityRegistryCacheTest.php b/tests/Feature/EntityRegistryCacheTest.php index e882cfea..8592e598 100644 --- a/tests/Feature/EntityRegistryCacheTest.php +++ b/tests/Feature/EntityRegistryCacheTest.php @@ -18,12 +18,12 @@ useCachedResourceDiscovery(ttl: 600); }); -function useCachedResourceDiscovery(int $ttl): void +function useCachedResourceDiscovery(int $ttl, ?string $version = null): void { config()->set('custom-fields.entity_configuration', EntityConfigurator::configure() ->discover([]) - ->cache(true, $ttl) + ->cache(true, $ttl, $version) ); rebuildEntityManager(); @@ -95,3 +95,50 @@ function entitiesSeenInPanel(string $panelId): EntityManager expect(Cache::has('custom_fields_entities:admin'))->toBeFalse() ->and(Cache::has('custom_fields_entities:portal'))->toBeFalse(); }); + +it('stores the registry under the configured cache version', function (): void { + useCachedResourceDiscovery(ttl: 600, version: 'deploy-2'); + + entitiesSeenInPanel('admin')->getEntities(); + + expect(Cache::has('custom_fields_entities:deploy-2:admin'))->toBeTrue() + ->and(Cache::has('custom_fields_entities:admin'))->toBeFalse(); +}); + +it('ignores a registry cached under another version', function (): void { + Cache::put('custom_fields_entities:deploy-1:admin', [], 600); + + useCachedResourceDiscovery(ttl: 600, version: 'deploy-1'); + expect(entitiesSeenInPanel('admin')->hasEntity(Post::class))->toBeFalse(); + + useCachedResourceDiscovery(ttl: 600, version: 'deploy-2'); + expect(entitiesSeenInPanel('admin')->hasEntity(Post::class))->toBeTrue(); +}); + +it('treats an empty cache version as no version', function (): void { + useCachedResourceDiscovery(ttl: 600, version: ''); + + entitiesSeenInPanel('admin')->getEntities(); + + expect(Cache::has('custom_fields_entities:admin'))->toBeTrue(); +}); + +it('clears the registry cached under the current version', function (): void { + useCachedResourceDiscovery(ttl: 600, version: 'deploy-2'); + + entitiesSeenInPanel('admin')->getEntities(); + + expect(Cache::has('custom_fields_entities:deploy-2:admin'))->toBeTrue(); + + $this->artisan('custom-fields:clear-cache')->assertSuccessful(); + + expect(Cache::has('custom_fields_entities:deploy-2:admin'))->toBeFalse(); +}); + +it('keeps the cache version through config caching', function (): void { + $configurator = EntityConfigurator::configure()->cache(true, 600, 'deploy-2'); + + $restored = eval('return '.var_export($configurator, true).';'); + + expect($restored->getCacheVersion())->toBe('deploy-2'); +});