Cache.php

<?php declare(strict_types = 1);

namespace PHPStan\Cache;

use PHPStan\DependencyInjection\AutowiredParameter;
use PHPStan\DependencyInjection\AutowiredService;

#[AutowiredService]
final class Cache
{

	private ?bool $arenaUsable = null;

	public function __construct(
		#[AutowiredParameter(ref: '@cacheStorage')]
		private CacheStorage $storage,
	)
	{
	}

	/**
	 * @param non-empty-string $key
	 */
	public function load(string $key, string $variableKey): mixed
	{
		// Every entry is also shared across the run's parallel workers
		// through the shared-memory arena (turbo extension only; the seam is
		// a no-op otherwise): whichever process loads or saves an entry first
		// publishes it, and the others skip reading and unserializing the
		// cache file. The arena's codec covers scalars, arrays and plain
		// value objects, and interns repeated strings on read like include()
		// does; payloads it cannot represent just stay per-worker.
		//
		// What a load publishes is only a copy of the file and does not
		// displace an entry already there. What save() publishes replaces it:
		// a caller that finds an entry out of date by checking it after the
		// load (FileTypeMapper checks the hashes of the files a name scope map
		// was created from) creates the value again and saves it, and every
		// process after that has to get the new value, not the one it rejected.
		$arenaKey = null;
		if ($this->isArenaUsable()) {
			$arenaKey = 'fcs:' . $key . "\0" . $variableKey;
			$cached = ArenaCache::lookup($arenaKey);
			if ($cached !== null) {
				return $cached;
			}
		}

		$data = $this->storage->load($key, $variableKey);
		if ($data !== null && $arenaKey !== null) {
			ArenaCache::publish($arenaKey, $data);
		}

		return $data;
	}

	/**
	 * @param non-empty-string $key
	 */
	public function save(string $key, string $variableKey, mixed $data): void
	{
		$this->storage->save($key, $variableKey, $data);

		if (!$this->isArenaUsable()) {
			return;
		}

		ArenaCache::replace('fcs:' . $key . "\0" . $variableKey, $data);
	}

	/**
	 * Whether this process is attached to a run's arena — probed once with a
	 * canary record because the answer is not directly observable through
	 * the seam: without the extension or without an arena the publish is a
	 * no-op and the canary never appears. Workers attach at boot, before any
	 * cache traffic; a process that touches the cache before its arena
	 * exists just stays unshared for its lifetime.
	 */
	private function isArenaUsable(): bool
	{
		if ($this->arenaUsable === null) {
			ArenaCache::publish('fcs-arena-canary', true);
			$this->arenaUsable = ArenaCache::hasRecord('fcs-arena-canary');
		}

		return $this->arenaUsable;
	}

}