Self-contained final class of static methods for path string manipulation covering UNIX, Windows (drive letters, backslash/forward-slash mixing, the 'C:' special case), and stream wrappers (phar://, file://). canonicalize() collapses '.'/'..' segments while correctly preserving leading '..' on relative paths, expands '~' to the home directory, and caches results in a bounded 1250-entry buffer trimmed to 1000 to prevent memory leaks and performance decay. Other methods include join(), makeAbsolute()/makeRelative() with root/drive-letter validation, getLongestCommonBasePath(), isBasePath(), getDirectory() (fixing documented dirname() shortcomings), and extension handling. It imports only its own exception classes, so an engineer can copy it verbatim into any PHP project — it is a reference implementation for path-manipulation edge cases that PHP's built-in functions get wrong.

The tempnam() and dumpFile() methods form a production-grade safe file-writing pattern. tempnam() generates unique names via random_bytes, forces umask(0o077) so files are created private like native tempnam(), uses fopen mode 'x+' to atomically check existence and create in one step (eliminating TOCTOU vulnerabilities), retries up to 10 attempts on collision, and falls back to a loop for stream wrappers such as gs:// or file://. dumpFile() builds on this with write-to-temp-then-rename atomicity, symlink dereferencing to the real file, preservation of the target's existing permissions, and guaranteed temp-file cleanup in a finally block even on failure. This is directly reusable as a reference for crash-safe file persistence in any PHP application.

The private box() helper installs a scoped error handler around every native PHP filesystem call, capturing warnings/errors into a static lastError property and letting each public method throw a structured IOException that includes the offending path — instead of silently returning false or leaking PHP warnings. The companion assertFunctionExists() guard catches disabled functions (e.g., when symlink or link is disabled in php.ini) and produces an actionable message. This pattern of wrapping fallible C-level functions so all failures surface as typed, contextual exceptions is directly extractable for any PHP library wrapping native calls.

The remove()/doRemove() implementation solves the genuinely hard cases of deletion: it reverses input order so children are removed before parents, unlinks symlinks first so iterators never recurse into link targets, works around the Windows symlink unlink bug (PHP #52176) with an unlink-or-rmdir fallback, and handles read-only directories by renaming the target to a random hidden temp name before recursive deletion (restoring it if the final rmdir fails and re-checking file_exists to distinguish stale metadata from real errors). Permission-denied failures are detected and rethrown as IOException with the specific file path. Robust cross-platform deletion logic that most applications get wrong.