Product Decisions This Supports

Testing Strategy: Enables deterministic filesystem testing for Laravel applications, eliminating flaky tests caused by real disk I/O, permissions, or external storage dependencies (e.g., S3, FTP). Aligns with a shift-left testing approach by isolating filesystem logic early in the SDLC.
Roadmap for Observability: Justifies investment in debugging tools for filesystem-heavy features (e.g., storage drivers, file uploads, or caching layers). Example: A "filesystem replay" feature to debug production issues locally.
Build vs. Buy: Buy this package to avoid reinventing a virtual filesystem for testing, reducing technical debt. The MIT license and PHP stream wrapper integration lower adoption risk.
Use Cases:
- Unit/Integration Tests: Mock Illuminate\Filesystem, League\Flysystem, or custom storage adapters without side effects.
- Dynamic Code Testing: Safely require or include virtual files for plugin systems, templating engines, or runtime-generated PHP (e.g., Laravel’s Blade caching).
- CI/CD Optimization: Accelerate test suites by replacing disk-bound operations with in-memory VFS.
- Edge Case Simulation: Trigger PHP warnings/errors (e.g., missing files, permission denials) in controlled environments.
Developer Experience: Reduces context-switching for engineers testing filesystem logic by providing a consistent, isolated environment across local/dev/CI setups.

When to Consider This Package

Adopt if:
- Your Laravel app’s core functionality depends on filesystem operations (e.g., file uploads, storage drivers, caching, or dynamic PHP generation) and requires reliable, isolated testing.
- You’re building plugins, themes, or modules that interact with the filesystem and need runtime validation without eval().
- Your test suite is slow or flaky due to disk I/O, external storage dependencies, or permission issues.
- You prioritize CI/CD efficiency and want to eliminate filesystem-related test failures (e.g., "No such file or directory" in CI but not locally).
- Your team uses PHPUnit or Pest and needs a simple, battle-tested way to mock filesystem interactions.
Look elsewhere if:
- Your use case is trivial (e.g., testing a single file_exists() call) and a mock object (e.g., Mockery) or Laravel’s Storage::fake() suffices.
- You need advanced filesystem features missing from this package:
  - Symlinks (tracked in issues).
  - File locks or permissions (critical for concurrent access testing).
  - High-performance bulk operations (VFS may not match native filesystem speed).
- Your app heavily relies on symlinks or ACLs (e.g., a complex file-sharing system).
- You’re on PHP 8.x and want a more actively maintained alternative (e.g., webmozart/path-util for path manipulation, or php-vfsstream as a fork with updates).
- You’re using Laravel’s built-in testing helpers (e.g., Storage::fake()) for 80% of your needs and only require VFS for edge cases.

How to Pitch It (Stakeholders)

For Executives:

*"This package lets us test and debug filesystem-dependent features—like file uploads, storage drivers, or caching—without touching the real disk. It’s like a sandbox for files, saving time in development and CI/CD by eliminating flaky tests caused by disk I/O or external storage. For example:

Faster test suites: No more waiting for S3 or local disk operations in tests.
Reliable debugging: Simulate edge cases (e.g., missing files, permission errors) in a controlled environment.
Lower risk: MIT-licensed, widely used in PHP testing, and integrates seamlessly with Laravel.

Ask: Should we pilot this in our storage driver tests and plugin system to measure impact on test speed and reliability? The cost is minimal (a Composer dependency), and the upside is fewer production bugs from untested filesystem logic."*

For Engineering:

*"Why Use adlawson/vfs?

Isolated Testing: Mock filesystem operations for Laravel’s Storage, Flysystem, or custom file logic without side effects.
Dynamic Code Safety: Write/require PHP files at runtime (e.g., for plugins or templating) without eval().
CI/CD Efficiency: Tests run faster since they skip disk I/O.
Laravel Integration: Works with Illuminate\Filesystem, Storage facade, and third-party libraries like Symfony’s Filesystem.

How to Adopt:

Install:
```
composer require adlawson/vfs
```

Set Up in Tests:

$fs = \Vfs\FileSystem::factory('vfs://');
$fs->mount();
// Now use `vfs://path/to/file` in tests.

Leverage Laravel Helpers:

Storage::fake('local');
Storage::disk('local')->put('test.txt', 'Hello');
$this->assertEquals('Hello', file_get_contents('vfs://test.txt'));

Trade-offs:

No symlinks/locks (track GitHub issues).
PHP 5.4+ only (but works with Laravel’s PHP 8.x).
Global state: Mount/unmount carefully to avoid test pollution.

Proposal:

Phase 1: Replace disk I/O in storage tests with VFS.
Phase 2: Use for dynamic file generation in plugin system.
Phase 3: Extend to CI/CD for faster test runs.

Alternatives:

Laravel’s Storage::fake() (simpler for basic cases).
Custom mocks (higher maintenance).
php-vfsstream (fork with updates, but less adoption).

Next Steps:

Validate integration with our Filesystem and Storage tests.
Benchmark test speed improvements.
Document VFS usage in the testing guide."*

For QA/Testing Teams:

*"How This Improves Your Work:

No More "Works on My Machine": Tests pass consistently because they don’t depend on the real filesystem.
Faster Feedback: CI/CD runs complete quicker since tests skip disk operations.
Better Debugging: Easily reproduce filesystem errors (e.g., 'File not found') in staging-like environments.
Easier Onboarding: New hires can test filesystem logic without setting up local storage or cloud credentials.

Example Workflow:

Before: Test fails in CI because a file doesn’t exist on the test server.
After: Test fails deterministically in VFS, and you fix the logic locally.

Ask: Should we train the team on using VFS for these high-priority test suites? It’s a small change with big payoffs for reliability."*

Vfs Laravel Package