Filesystem Laravel Package

Getting Started

Start by installing the package via Composer: composer require joomla/filesystem "^4.0" (requires PHP 8.3+). The core API centers around two static classes: Joomla\Filesystem\File for file operations (upload, write, read, delete, extensions) and Joomla\Filesystem\Folder for directory operations (create, delete, copy, list files). The most common first use case is secure file uploads — review the README’s File::upload() example, but also consider using File::makeSafe() for sanitizing filenames and Helper::fileUploadMaxSize() (added in v3.1.0) to respect PHP’s upload_max_filesize and post_max_size.ini settings. Always validate MIME type yourself (extension-only checks are insufficient for security).

Implementation Patterns

• Upload Handling: Wrap upload logic in a helper class: validate size via $_SERVER['CONTENT_LENGTH'] or File::getFileUploadMaxSize(), check extension via File::getExt(), sanitize with File::makeSafe(), and move with File::upload(). Prefer uploading to a non-web-accessible path first, then move into place after validation.
• Path Normalization: Use Path::resolve() (since v1.6.0) to normalize mixed relative/absolute paths, especially when concatenating user-provided folder names.
• File Listing & Filtering: Folder::files($path, $filter = '*', $recursive = false, $usePrefix = false) supports wildcards and custom prefixes; use natsort or asort options (added in v3.0.0) for predictable ordering in list views.
• Cache Invalidation: When copying/moving folders, remember Folder::copy() now invalidates opcache (added in v3.1.1) to prevent stale includes — useful in live deployments without manual cache clearing.
• Error Handling: Prefer try/catch around destructive operations (delete, copy, move) as they throw \RuntimeException for permission or I/O issues (improved message in v3.1.1).

Gotchas and Tips

• Security: File::makeSafe() sanitizes *nix-unsafe chars (e.g., /, \0) but does NOT block dangerous extensions like .php. Always verify allowed extensions and consider MIME-type checks via finfo_file() or similar. Do not rely solely on extension filtering.
• Path Issues: On Windows, ensure consistent forward slashes (str_replace('\\', '/', $path)) when using Path::resolve() or constructing paths manually. The package does not normalize directory separators automatically.
• Legacy Confusion: Avoid 1.x/2.x patterns — Folder::add(), Folder::addFile(), and File::copy() signatures changed in v2.0+, requiring explicit root paths. Always check current method signatures.
• Missing Features: No built-in async I/O or streaming write APIs — For large file handling, use PHP’s native fopen/stream_copy_to_stream and combine with File::write() only for small metadata writes.
• Testing: Since the package is low-dependency, mocking filesystem operations is straightforward: wrap it in an interface (FilesystemInterface) and use a test double — the class is final in parts, so avoid extending it directly.
• Upgrade Risks: Jumping from 1.x to 4.x may break add() calls and substr() usage in older PHP environments. Run full test coverage and check CVE-2022-23794 if using <2.0.1 (path disclosure in errors).