Cache keys and storage

When we call a getter, the cache key is escaped before it is appended to the cache directory path. This prevents path traversal while still keeping the stored filename understandable during debugging.

Readable escaping

For example, this cache key:

$cache->get("https://example.com/test", fn() => "ok");

is stored using a URL-escaped filename inside the cache directory:

https%3A%2F%2Fexample.com%2Ftest

That is easier to inspect than a hash, while still ensuring the key cannot create nested paths such as ../outside-cache.

Choosing cache keys

Good cache keys are:

• stable for the same logical resource
• specific enough to avoid collisions
• easy for developers to recognise when inspecting cache files

Examples:

• user:105:profile
• product:blue-shirt:availability
• https://example.com/api/feed?page=2

Choosing a cache directory

The cache directory is supplied when the Cache object is constructed:

$cache = new GT\FileCache\Cache(__DIR__ . "/cache");

Choose a location that:

• is writable by the PHP process
• is safe to persist cached data in
• can be cleared without affecting source code or user uploads

For web applications, it is usually better to keep the directory outside the public document root unless exposing cache files intentionally.