Cache
in package
Backs `Cooper::loadFile()`'s default caching -- the Elixir original's `Cooper.Cache`. It caches the *pre-resolve* tree (parse, imports, loops, merge) per entry file and root, and reuses it as long as every file that contributed -- the entry file and every file it transitively imports -- still has the modification time it had when cached, and every import pattern (`import "parts/*.casc"`, braces too) still matches the files it matched then -- a file added where an import looks, or removed from there, is a change like an edited one.
${...} resolution is never cached: it re-runs against the current
environment on every load, hit or miss.
The cache lives in process memory: within one request for a classic PHP-FPM setup, across requests for a long-running worker (RoadRunner, Swoole, FrankenPHP worker mode, a queue consumer, a CLI daemon).
Environment-shaped trees
Some environment reads decide the tree's shape rather than a value
in it: a ${?NAME} guard, ${NAME} in an import path, ${NAME} in
an interpolated key. A cached entry remembers those values and is
dropped -- and re-parsed -- on the next load that sees any of them
changed, firing a CacheEvent::ENV_CHANGED event. This replaces the
Elixir original's background polling (watch_env), which PHP has no
process to run; checking synchronously on each load is also exact,
where polling is up to one interval stale.
A scheme:// import has no file to fingerprint; its content is only
re-read when something file-backed in the same load changes.
Events
listen() registers a callback receiving a CacheEvent -- the
counterpart of the Elixir original's telemetry events.
Table of Contents
Properties
- $entries : array<string, TreeResult}>
- $listeners : array<int, callable(CacheEvent): void>
- $nextListenerId : int
Methods
- clear() : void
- Removes every cached entry.
- fetch() : TreeResult|null
- The cached pre-resolve tree for `$path`/`$root`, or `null` on a miss: no entry, a contributing file changed, an import now matches different files, or a tree-shaping environment variable changed (which also drops the entry and fires `CacheEvent::ENV_CHANGED`).
- invalidate() : void
- Removes every cached entry for `$path` (under any root).
- listen() : int
- Registers a listener for cache events.
- populate() : TreeResult
- Populates (or refreshes) the entry for `$path`/`$root` by calling `$loader`, firing `CacheEvent::FILE_CHANGED` when this refreshes an entry whose files changed. A loader that throws caches nothing.
- unlisten() : void
- Removes a listener registered with `listen()`.
- __construct() : mixed
- emit() : void
- fingerprintValid() : bool
- Both halves of a fingerprint are compared against disk: a file edited or deleted changes its mtime, and a file added where an import looks -- or removed from there -- changes what the pattern expands to.
- key() : string
- mtime() : int|null
Properties
$entries
private
static array<string, TreeResult}>
$entries
= []
$listeners
private
static array<int, callable(CacheEvent): void>
$listeners
= []
$nextListenerId
private
static int
$nextListenerId
= 1
Methods
clear()
Removes every cached entry.
public
static clear() : void
fetch()
The cached pre-resolve tree for `$path`/`$root`, or `null` on a miss: no entry, a contributing file changed, an import now matches different files, or a tree-shaping environment variable changed (which also drops the entry and fires `CacheEvent::ENV_CHANGED`).
public
static fetch(string $path, string $root, array<string, string> $env) : TreeResult|null
Parameters
- $path : string
-
the entry file's absolute path
- $root : string
-
the root its bare imports resolve against
- $env : array<string, string>
-
the environment this load sees
Return values
TreeResult|null —the cached tree, or null on a miss
invalidate()
Removes every cached entry for `$path` (under any root).
public
static invalidate(string $path) : void
Parameters
- $path : string
-
the entry file, relative to the working directory or absolute
listen()
Registers a listener for cache events.
public
static listen(callable(CacheEvent): void $listener) : int
Parameters
- $listener : callable(CacheEvent): void
-
called synchronously, during the load that detects the change
Return values
int —an id for unlisten()
populate()
Populates (or refreshes) the entry for `$path`/`$root` by calling `$loader`, firing `CacheEvent::FILE_CHANGED` when this refreshes an entry whose files changed. A loader that throws caches nothing.
public
static populate(string $path, string $root, array<string, string> $env, callable(): TreeResult $loader) : TreeResult
Parameters
- $path : string
-
the entry file's absolute path
- $root : string
-
the root its bare imports resolve against
- $env : array<string, string>
-
the environment the load used
- $loader : callable(): TreeResult
-
produces the tree
Return values
TreeResult —the freshly loaded tree
unlisten()
Removes a listener registered with `listen()`.
public
static unlisten(int $id) : void
Parameters
- $id : int
-
the id
listen()returned
__construct()
private
__construct() : mixed
emit()
private
static emit(CacheEvent $event) : void
Parameters
- $event : CacheEvent
fingerprintValid()
Both halves of a fingerprint are compared against disk: a file edited or deleted changes its mtime, and a file added where an import looks -- or removed from there -- changes what the pattern expands to.
private
static fingerprintValid(array<string, int|null> $fingerprint, array<int, ImportGlob> $globs) : bool
Parameters
- $fingerprint : array<string, int|null>
- $globs : array<int, ImportGlob>
Return values
boolkey()
private
static key(string $path, string $root) : string
Parameters
- $path : string
- $root : string
Return values
stringmtime()
private
static mtime(string $file) : int|null
Parameters
- $file : string