Filesystem Laravel Package

Product Decisions This Supports

• Cross-platform file operations: Standardize file handling across Windows, Linux, and macOS (e.g., path normalization, temporary file/directory creation).
• Testability: Simplify unit testing with FileSystemTestCase, FakeFileSystem, and SplFileInfoBuilder to mock filesystem interactions without complex mocks.
• Read-only environments: Support for ReadOnlyFileSystem to enforce immutability in CI/CD pipelines, deployments, or read-heavy applications.
• Broad Symfony compatibility (7.x and 8.x): Backport readFile() for pre-Symfony 7.1 projects, and run cleanly on Symfony 8 as of v2.0.1 — useful for teams tracking the newest Symfony releases or planning an upgrade path.
• Dependency injection vs. static usage: Flexibility to use dependency injection (via FileSystem interface) or static FS class for simplicity.
• Finder utilities: Streamline file discovery with createFinder() and SplFileInfoFactory for consistent path handling in tests.

When to Consider This Package

• Avoid if:
  • Your project already uses Laravel’s built-in filesystem (e.g., Storage facade) or Flysystem, which may overlap with core functionality.
  • You need advanced cloud storage (e.g., S3, GCS) – use Flysystem adapters instead.
  • Your team prefers minimal dependencies and the Symfony Filesystem component suffices.
• Consider if:
  • You require cross-platform path handling (e.g., Windows/Linux path normalization).
  • Your tests rely heavily on filesystem interactions and need mocking utilities.
  • You work with Symfony Finder and need SplFileInfo compatibility in tests.
  • You need temporary file/directory management with custom prefixes/directories.
  • Your project uses Symfony 7.x or 8.x (PHP 8.2+) and wants to avoid reinventing filesystem utilities — v2.0.1 adds Symfony 8 support, so the package is safe to keep through a Symfony 8 upgrade.
  • You are planning or mid-flight on a Symfony 8 migration and need a filesystem dependency that won’t block the upgrade.

How to Pitch It (Stakeholders)

For Executives: "This package standardizes filesystem operations across platforms, reducing bugs in file paths (e.g., Windows/Linux) and simplifying testing. It’s a lightweight wrapper around Symfony’s filesystem, adding utilities like temporary file creation and read-only modes—critical for CI/CD and deployments. The latest patch (2.0.1) adds Symfony 8 support, so it stays compatible as we move onto current Symfony releases without extra migration work. Low risk (BSD-3 license, minimal dependencies), and it saves dev time by eliminating custom path-handling logic."

For Engineering: *"Leverage this to:

1. Unify path handling (e.g., escapePath(), realPath()) across environments.
2. Mock filesystem operations in tests with FakeFileSystem or SplFileInfoBuilder, cutting test setup time by 30%+.
3. Enforce read-only modes in production-like tests or deployments.
4. Avoid reinventing wheel for temp files/dirs or Finder utilities. Dependencies: Only Symfony Filesystem (already in Laravel). v2.0.1 is a patch release adding Symfony 8 compatibility — no BC breaks and no code changes required on our side; it simply widens the supported Symfony range and de-risks our Symfony 8 upgrade path."*