Method caching

#[Cacheable] remembers what a method returned: the first call runs the body, later calls with the same key get the stored value without a trip to the database. The set of attributes, their parameters and their behaviour come from Spring Cache.

What this is and why

Method caching keeps what a method returned, so the next call with the same arguments gets the ready answer instead of computing it again.

The problem. Some data is read far more often than it changes: a list of countries, a product card, the settings of a plan. Every request still goes to the database for it, and the load grows with traffic although the answer is the same every time. A cache written by hand is a “is it cached” check, a write after the computation and a removal on change, smeared across every method of the service. A forgotten removal goes unnoticed until a user sees stale data.

The solution. Mark the method with an attribute, and the framework checks the cache, runs the body on a miss and stores the result. Removal on change is declared the same way, with an attribute on the method that changes the data.

Ancestry

Where Winter differs from Spring

The key is a template, not an expression. Instead of SpEL, parameters are substituted: '{id}', '{filter.region}:{page}'. The template is read once, at build time, and a misspelt parameter name stops the build instead of turning into a key that matches nothing. There is no condition or unless.

The lifetime is set right here. In Spring a TTL is the concern of a particular store; in Winter it is the ttl parameter of the cache and of the attribute.

A call to a sibling method is cached too. In Spring @Cacheable does not apply when the method is called from the same class through this. In Winter the proxy is a subclass of your service, so a call through $this goes through the cache.

Every hit is a copy. The store keeps the serialized value, and each call gets its own instance. Changing an object taken from the cache and then seeing the change in another request is not possible.

Quick start

Three steps: enable it, declare a cache, mark a method.

use Flytachi\Winter\Kernel\App\Attribute\EnableCaching;
use Flytachi\Winter\Kernel\App\Attribute\EnableWeb;

#[EnableWeb]
#[EnableCaching]
final class Application extends WinterApplication
{
  public static function main(array $argv): never
  {
      parent::run($argv);
  }
}

namespace Main\Config;

use Flytachi\Winter\Kernel\Cache\CacheConfigurer;
use Flytachi\Winter\Kernel\Cache\Caches;

final class CacheConfig implements CacheConfigurer
{
  public function configureCaches(Caches $caches): void
  {
      $caches->table('countries');   // the defaults: 64 entries up to 16 KB, ≈1.6 MB
  }
}

namespace Main\Service;

use Flytachi\Winter\Kernel\Cache\Attribute\Cacheable;

class CountryService
{
  #[Cacheable('countries', key: '{code}')]
  public function find(string $code): ?Country
  {
      return $this->repository->find($code);   // runs once per code
  }
}

The service is injected as usual — the container hands out the cached version:

#[Inject]
private CountryService $countries;

$this->countries->find('UZ');   // the body ran, the result is stored
$this->countries->find('UZ');   // from the cache, no database query

Stores

Each cache is declared in a CacheConfigurer and lives in one of four stores: table and memory in the server’s memory, file and redis outside it — so console commands see them and a restart does not wipe them.

Which one to choose

In short: one server and changing data — table; must survive a restart or be seen from the console — file; several instances — redis; data that does not change or goes stale on its own by ttl — memory.

table — shared by every process

The table is created in the master process before the workers are forked from it, which is why it is shared: a value computed by one worker is served by all the others at once, and a removal in one worker removes the entry for all. Processes beside the server, #[EnableProcess], #[EnableDaemon], #[EnableScheduler], see it too.

The defaults are sized for the most common case — a handful of values: a token, settings, a short reference list. Such a table takes ≈1.6 MB.

Ready-made table settings

// 1. A handful of values — a token, settings, a short list.  ≈1.6 MB
$caches->table('api-token');

// 2. A reference list per item: up to a thousand 2 KB entries. ≈3.2 MB
$caches->table('countries', rows: 1_024, valueSize: 2 * 1024);

// 3. Entities by id: ten thousand 2 KB cards.                 ≈51 MB
$caches->table('products', rows: 10_000, valueSize: 2 * 1024, ttl: 300);

The memory figures are measured on a live process. What matters is not how many entries there will be but how many there may become. When the table fills up, the entry is not stored, and a warning appears in the log.

What fits in a value

valueSize limits the value after serialize(). Measurements, so there is no guessing:

A rule of thumb: one entity record takes about 350 bytes, and an object and an array of the same shape weigh almost the same. The exact number for your own data:

echo strlen(serialize($service->all()));   // bytes — compare with valueSize

How much memory a table takes

The memory is reserved in full at startup — however many entries appear later. Swoole rounds the number of rows up to a power of two and adds room for collisions, so the estimate is:

power of two ≥ rows  ×  1.5  ×  (valueSize + 120) bytes

rows: 64,     valueSize: 16384  →     64 × 1.5 × 16504  ≈ 1.6 MB
rows: 10_000, valueSize: 4096   →  16 384 × 1.5 × 4216   ≈ 99 MB

The total shows in the startup banner:

   web         http://0.0.0.0:8000
 cache       2 table · 1 memory · ≈53 MB shared

When a value does not fit

A value longer than valueSize, or a write into a full table, is not stored: the method still returns the right result, just without the cache. Swoole itself silently truncates a string that is too long, and a truncated value can no longer be read — so such a write never reaches the table, and the old entry under the same key is removed so nothing stale is served.

Before refusing, the table drops its expired entries once. If there is still no room, a warning is logged — at most once a minute per cache, with a count of skipped writes:

[WARN ] Cache 'settings' skipped a write: a value of 21480 bytes does not fit valueSize 16384;
raise valueSize in the CacheConfigurer. The value was returned uncached; 12 write(s) skipped
since the last warning.

Such a message means the cache stopped working for part of the data and the load on the database came back. Raise what the message names: valueSize or rows.

memory — one per worker

A plain PHP array: nothing is reserved up front, and a value of any size fits. The price is that every worker has its own copy and computes it itself.

When there are more than maxItems entries, the one read least recently goes. That is ordinary work for such a cache, and it logs no warnings.

Memory grows as entries are written: each entry costs its value plus about 370 bytes. A thousand entities of ~350 bytes is about 0.7 MB per worker, five thousand about 3.4 MB.

Ready-made memory settings

// 1. A reference list that does not change until a deploy: lives as long as the worker.
$caches->memory('currencies');

// 2. Rates: a hundred pairs, each lives a minute.
$caches->memory('rates', maxItems: 100, ttl: 60);

// 3. Stock levels: thousands of items, half a minute.
$caches->memory('stock', maxItems: 5_000, ttl: 30);

file — on disk

Entries are files in storage/cache/winter-cache/<name>/. Every worker and process reads them, call commands see them, and a restart or a deploy does not wipe them. A write is atomic — a temporary file and a rename — so no one ever reads half a value.

A read takes about 17 µs, a write about 150 µs: dozens of times slower than table, but hundreds of times faster than a database query. Expired files go when read and in one sweep at server start; call storage clean empties the folder as well.

// A token that survives a restart and is seen by call commands.
$caches->file('api-token', ttl: 3300);

// Settings a console command resets.
$caches->file('settings', version: 'v2');

Under FPM, where a process lives for one request, this store still caches.

redis — shared by every instance

The only store several instances of the application share: replicas in Kubernetes, servers behind a load balancer. A removal on one server is seen by all of them. It needs the winter-redis package — without it a redis() declaration stops the start with a hint on what to install.

$caches->redis('products', MainRedisConfig::class, ttl: 300);

Keys in Redis are visible as they are: #[Cacheable('products', key: '{id}')] with version v2 writes to cache:products:v2:42. allEntries and call cache clear remove only keys with this cache’s prefix — the rest of the database is left alone.

When a store is unreachable

A broken cache must not break the application. If Redis does not answer or a file cannot be written:

• a read counts as a miss — the method runs and returns the right result;
• a write is skipped;
• a warning is logged — at most once a minute per cache, with a count;
• the worker leaves the store alone for 5 seconds and runs without the cache, then tries again.

The pause matters. An unreachable Redis does not always refuse at once: an attempt may wait out the connect timeout — about three seconds with the winter-redis defaults. Without the pause every call would pay that twice, to read and to write, and an application that “did not fall over” would in fact stand still.

Attributes

#[Cacheable] — return from the cache or compute

#[Cacheable('products', key: '{id}', ttl: 300)]
public function find(int $id): ?Product

If the entry exists, the body does not run. If not, it runs and the result is stored. An exception from the body is not cached: the next call tries again.

#[CachePut] — always run and refresh

For methods that change data and return the new state. The body always runs, and the result is written to the cache — the next read finds it.

#[CachePut('products', key: '{result.id}')]
public function save(Product $product): Product

The parameters are those of #[Cacheable], except sync. The key may use {result} — the returned value. With cacheNull: false a null result removes the entry instead of keeping the old one.

#[CacheEvict] — remove

#[CacheEvict('products', key: '{id}')]
#[CacheEvict('product-lists', allEntries: true)]
public function delete(int $id): void

The attribute is repeatable: one method can clean several caches. It combines with #[Cacheable] or #[CachePut] on the same method.

By default the entry is removed after the body completes successfully. If the body throws, the change did not happen and the entry stays — it is still valid. With beforeInvocation: true the entry is removed before the call, whatever happens next.

#[CacheConfig] — class defaults

#[CacheConfig('products', ttl: 300)]
class ProductService
{
  #[Cacheable(key: '{id}')]                 // cache products, 300 seconds
  public function find(int $id): ?Product

  #[Cacheable(key: 'all', ttl: 60)]         // cache products, 60 seconds
  public function all(): array
}

A value on the method always wins over the one on the class.

Keys

The key decides which entry a call belongs to. It is a template over the method’s parameter names:

A key can hold strings, numbers, bool, null, enums, arrays and objects with __toString(). A whole object does not go into a key — name its property: '{order.id}'.

Without key the key is built from every argument in order. A method without parameters has a constant key — a single entry.

Lifetime

ttl is in seconds. The value comes from the first level that sets one:

1. the attribute parameter on the method;
2. #[CacheConfig] on the class;
3. the cache’s ttl in the CacheConfigurer;
4. none — the entry lives until it is removed or the application restarts.

ttl: 0 means “never expires” and overrides the level above — this is how one method of a class with #[CacheConfig(ttl: 60)] is made permanent. An expired entry counts as a miss when read: the method runs again and its result overwrites the entry.

null is cached too

By default, as in Spring, null is stored like any other value: “there is no such record” is an answer too, and the database should not get the same empty query on every call.

The consequence: if the record appears later, the cache keeps returning null until it is removed. The method that creates it has to tell the cache:

#[Cacheable('users', key: '{email}')]
public function findByEmail(string $email): ?User

#[CacheEvict('users', key: '{user.email}')]
public function register(User $user): User

If that is inconvenient, turn off storing an empty result: cacheNull: false.

sync — one computation per miss

When an entry expires under load, dozens of requests miss at once and go to the database for the same thing simultaneously. With sync: true the first request computes the value, the others wait for it and get the ready result.

#[Cacheable('reports', key: 'daily', ttl: 600, sync: true)]
public function dailyReport(): Report

Build-time checks

Everything that can be checked from the declaration is checked by call di build and at application startup — not on the first call in production:

A misspelt cache name on #[CacheEvict] is the dangerous one: such a method would simply remove nothing, and users would see stale data. That is why the name is checked before startup.

Class and method requirements

The same as for #[Async], because the same mechanism is at work — a generated subclass:

• the class is not final; the method is not final, static or private;
• the service comes from the container, not from new — otherwise the proxy does not apply, and call di build warns about it;
• #[Cacheable] and #[CachePut] sit on a method that returns a storable value: not void, never, Generator, Closure, callable or iterable;
• the value has to pass through serialize(): a closure inside an object will not be stored — the method returns it uncached and logs a warning.

One class can mix #[Async] methods and cached methods — it gets one shared proxy. They cannot be combined on one method.

What the cache does not see

• Console commands — table and memory. call … is a separate process with its own memory: a command that changes data will not clear such a cache of the server. If you need that, use file or redis — both a #[CacheEvict] in the command and call cache clear reach them.
• Other instances of the application — everything but redis. Each container holds its own table and its own folder; a change in one does not remove the entry in another.
• FPM — table and memory. A process lives for one request, and such a cache with it.

Deploys and old data

table and memory are empty after a restart. file and redis survive a deploy — and with it the entries written by the old code. If the class of a value changed, say a new typed property appeared, the object from such an entry comes back incomplete.

Three measures deal with it:

• an entry that no longer restores — a class that is gone, corrupted bytes — counts as a miss: it is removed and computed again;
• version on the cache — change it and older entries are simply not found: in redis they expire on their own, in file the sweep removes them;
• call cache clear — clear the cache explicitly, for instance in a deploy script.

php call cache clear --all   # every file and redis cache
php call run

Examples

An external API token for an hour

The most common case. The auth service issues a token for an hour, and requesting it on every call is an extra delay and a risk of hitting the issue limit.

use Flytachi\Winter\Kernel\Cache\Attribute\CacheEvict;
use Flytachi\Winter\Kernel\Cache\Attribute\Cacheable;

class PaymentGateway
{
  #[Cacheable('api-token', key: 'payment', ttl: 3300, sync: true, cacheNull: false)]
  public function token(): string
  {
      $response = $this->http->post('https://auth.example.com/oauth/token', [
          'client_id'     => $this->clientId,
          'client_secret' => $this->clientSecret,
          'grant_type'    => 'client_credentials',
      ]);

      return $response['access_token'];
  }

  #[CacheEvict('api-token', key: 'payment')]
  public function forgetToken(): void
  {
  }

  public function charge(Order $order): array
  {
      $response = $this->send($order, $this->token());

      // The token was revoked early: forget it, get a new one, retry once.
      if ($response['status'] === 401) {
          $this->forgetToken();
          $response = $this->send($order, $this->token());
      }

      return $response;
  }
}

$caches->table('api-token');   // the defaults: ≈1.6 MB, room for dozens of tokens

What matters here:

• ttl: 3300 — 55 minutes for an hour-long token. The margin keeps the cache from handing out a token with a second left: a request with it goes out and comes back 401.
• sync: true — when the token expires, dozens of simultaneous requests do not go for a new one at once: one gets it, the others wait for it.
• cacheNull: false — if the auth service returned an empty response, it is not remembered for 55 minutes. An exception is not cached in any case.
• key: 'payment' — one api-token cache can hold the tokens of several services under different keys.
• $this->token() inside charge() goes through the cache: the proxy is a subclass of the service, so a call to its own method is cached too.
• table, not memory: one token for every worker and process, and forgetToken() resets it for all of them at once. To survive a restart — file('api-token'); with several instances — redis('api-token', …). The attributes stay the same.

Constants from the database

Settings, tariffs, texts — read on every request, changed once a week.

#[CacheConfig('settings')]
class SettingsService
{
  #[Cacheable(key: 'all')]
  public function all(): array
  {
      return $this->repository->pairs();   // ['name' => 'value', ...]
  }

  public function get(string $name, ?string $default = null): ?string
  {
      return $this->all()[$name] ?? $default;   // from the cache
  }

  #[CacheEvict(key: 'all')]
  public function set(string $name, string $value): void
  {
      $this->repository->save($name, $value);
  }
}

$caches->table('settings');   // up to 16 KB of settings — hundreds of pairs

All the settings are one value under the key 'all': one database query for everyone, and set() resets it in every worker at once. No ttl is needed — the entry lives until it is changed. If the settings are changed bypassing the service (by hand in the database), add a ttl, say 600: the change is then picked up within ten minutes.

A reference list

The data hardly ever changes, the key is a code, there is nothing to remove.

#[CacheConfig('currencies')]
class CurrencyService
{
  #[Cacheable(key: '{code}')]
  public function find(string $code): ?Currency
  {
      return $this->repository->find($code);
  }

  #[Cacheable(key: 'all')]
  public function all(): array
  {
      return $this->repository->findAll();
  }
}

$caches->memory('currencies');   // changes only with a deploy — memory is enough

An entity: read, change, remove

#[CacheConfig('products', ttl: 300)]
class ProductService
{
  #[Cacheable(key: '{id}')]
  public function find(int $id): ?Product
  {
      return $this->repository->find($id);
  }

  // The new state goes straight into the cache, the lists are reset.
  #[CachePut(key: '{result.id}')]
  #[CacheEvict('product-lists', allEntries: true)]
  public function save(Product $product): Product
  {
      return $this->repository->save($product);
  }

  #[CacheEvict(key: '{id}')]
  #[CacheEvict('product-lists', allEntries: true)]
  public function delete(int $id): void
  {
      $this->repository->delete($id);
  }

  #[Cacheable('product-lists', key: '{category}:{page}', ttl: 60)]
  public function byCategory(string $category, int $page = 1): array
  {
      return $this->repository->byCategory($category, $page);
  }
}

$caches
  ->table('products', rows: 10_000, valueSize: 2 * 1024)         // ≈51 MB
  ->table('product-lists', rows: 512, valueSize: 16 * 1024);     // a page of up to 45 cards, ≈12 MB

Stock levels — change often, go stale fast

The value lives half a minute, no shared memory needed: each worker keeps its copy.

#[Cacheable('stock', key: '{sku}', ttl: 30)]
public function available(string $sku): int

// CacheConfig:
$caches->memory('stock', maxItems: 5_000);

Next

• Asynchronous calls — the same proxy mechanism for #[Async]
• The cache command — inspecting and clearing file and redis caches
• The di command — building proxies and checking cache names
• Dependency injection — why the service is injected, not constructed
• Web layer configuration — SERVER_WORKERS and worker restarts