Symfony Filesystem

Symfony Filesystem is a small, dependency-light PHP component that wraps the native filesystem functions (copy, mkdir, chmod, symlink, remove, rename) with consistent, exception-based error handling instead of PHP’s warning-and-false-return convention. It also ships a Path helper for normalizing, joining, and comparing filesystem paths across Windows and Unix, which matters for any tool that has to run predictably on more than one OS.

Because it has almost no dependencies and a stable, narrow API, it’s one of the most widely reused Symfony components outside of full Symfony applications — Composer itself, PHPUnit, and countless CLI tools pull it in just for reliable file operations.

What You Get

• A Filesystem class with copy, mkdir, remove, chmod, chown, symlink, hardlink, rename, and touch operations that throw exceptions instead of returning false
• A Path utility for canonicalizing, joining, making relative, and comparing paths consistently across Windows and Unix
• Atomic file writes via dumpFile(), which writes to a temp file and renames it to avoid partially-written files
• Stream-wrapper-aware operations (e.g. copy() works with local files, FTP, and other PHP stream wrappers)
• Typed exception hierarchy (IOException, FileNotFoundException, InvalidArgumentException) for precise error handling

Common Use Cases

• Build scripts and CLI tools that need to copy, move, or clean up directories reliably across operating systems
• Framework and library internals that write cache, config, or temp files and want atomic, exception-safe writes
• Deployment and asset-pipeline tooling that needs to normalize and compare paths supplied by users or config files
• Any Composer package that wants filesystem helpers without pulling in the full Symfony framework

Under The Hood

Architecture - The component is deliberately flat: a single Filesystem class (781 lines) holds all mutating disk operations, delegating low-level calls through a private box() wrapper that captures PHP’s error-to-exception translation in one place, while a separate static Path class (828 lines) handles pure string/path logic with no I/O. This split keeps side-effecting code isolated from testable, deterministic path math.

Tech Stack - Pure PHP 8.4+ with almost no runtime dependencies beyond symfony/deprecation-contracts and two polyfills (ctype, mbstring), making it safe to install standalone without pulling in the rest of Symfony. Dev-only dependency on symfony/process supports test fixtures that shell out.

Code Quality - Tests live in Tests/FilesystemTest.php and Tests/PathTest.php, covering the public API extensively including edge cases like FTP stream wrappers and Windows path separators; a shared FilesystemTestCase sets up per-test temp directories. Naming is consistent and every public method has a docblock stating thrown exceptions.

API Design - Methods map directly to POSIX/Windows filesystem verbs (copy, mkdir, remove, chmod, chown, symlink, rename, touch), so developers coming from raw PHP functions have almost no new API surface to learn — the main adjustment is catching typed exceptions instead of checking boolean returns.