Pair framework: FilesystemMetadata class

Pair\Core\FilesystemMetadata caches lightweight filesystem checks for the current PHP process.

It is intentionally small and currently focuses on file_exists() checks used during bootstrap, routing, and module controller discovery.

This is not the general application cache API. Use it only for framework metadata where stale values are acceptable until explicit invalidation.

---

Why it exists

Pair resolves several files by convention:

• APPLICATION_PATH/.env
• root routes.php
• module routes.php
• module controller.php

Those checks are cheap individually, but repeated bootstrap and routing flows can perform the same filesystem lookups more than once in the same PHP process.

FilesystemMetadata keeps those lookups deterministic and avoids repeated work.

---

Methods

FilesystemMetadata::fileExists(string $path): bool

Returns whether a path exists, caching the result by the exact path string.

use Pair\Core\FilesystemMetadata;

if (FilesystemMetadata::fileExists(APPLICATION_PATH . '/routes.php')) {
    // Import custom routes.
}

Repeated calls for the same path return the cached value.

---

FilesystemMetadata::clear(?string $path = null): void

Clears cached filesystem metadata.

Pass a path to invalidate only one cached lookup:

FilesystemMetadata::clear(APPLICATION_PATH . '/routes.php');

Call it without arguments to clear every cached path:

FilesystemMetadata::clear();

Use explicit invalidation in tests, installers, module generators, deployment scripts, and long-running CLI commands that create, delete, or replace route/controller files while the same PHP process keeps running.

---

Best practices

• Do not use this as an application data cache.
• Do not cache mutable file contents here.
• Prefer explicit invalidation after filesystem writes.
• Keep deployment flows simple: after a normal PHP-FPM request restart or a fresh CLI process, the cache starts empty.