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.
• Legacy Symfony compatibility: Backport readFile() for pre-Symfony 7.1 projects or maintain consistency in tests.
• 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+ or PHP 8.2+ and wants to avoid reinventing filesystem utilities.

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. 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). No BC breaks since v2.0.0."*