Getting Started

Minimal Steps

Installation:

composer require symfony/filesystem

Add to composer.json under require:

"symfony/filesystem": "^8.0"

First Use Case: Use the Filesystem class for basic file/directory operations:

use Symfony\Component\Filesystem\Filesystem;

$fs = new Filesystem();

// Create a directory
$fs->mkdir('path/to/directory');

// Copy a file
$fs->copy('source.txt', 'destination.txt');

// Remove a file
$fs->remove('file.txt');

Where to Look First:
- Official Documentation
- Symfony\Component\Filesystem\Filesystem class methods (e.g., mkdir, copy, remove, dumpFile, exists).
- Symfony\Component\Filesystem\Path class for path manipulation (e.g., normalize, getFilename, isAbsolute).

Implementation Patterns

Core Workflows

1. File and Directory Management

Atomic Writes: Use dumpFile() to write files atomically, reducing race conditions:
```
$fs->dumpFile('config.json', json_encode($config));
```
Recursive Operations: Use mirror() to replicate directory structures:
```
$fs->mirror('source_dir', 'destination_dir');
```

2. Path Manipulation

Normalize Paths: Ensure cross-platform compatibility:

$normalizedPath = Path::normalize('/path/with/../segments');

Relative Paths: Convert absolute paths to relative:

$relativePath = Path::makePathRelative('/var/www/html', '/var/www/html/storage');

3. Permissions and Ownership

Set Permissions: Use chmod() for secure file access:
```
$fs->chmod('file.txt', 0644);
```
Change Ownership: Use chown() (Linux/macOS only):
```
$fs->chown('file.txt', 1000);
```

4. Temporary Files

Create and Clean Up Temp Files:

$tempFile = tempnam(sys_get_temp_dir(), 'prefix');
file_put_contents($tempFile, 'data');
$fs->remove($tempFile); // Cleanup

5. Integration with Laravel

Service Provider Binding:

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->singleton(Filesystem::class, function () {
        return new Filesystem();
    });
}

Artisan Commands:

use Symfony\Component\Filesystem\Filesystem;

class BackupCommand extends Command
{
    protected $fs;

    public function __construct(Filesystem $fs)
    {
        parent::__construct();
        $this->fs = $fs;
    }

    public function handle()
    {
        $this->fs->mirror(storage_path('app'), backup_path('app'));
    }
}

6. Handling Edge Cases

Check Existence Before Operations:

if ($fs->exists('file.txt')) {
    $fs->remove('file.txt');
}

Handle Errors Gracefully:

try {
    $fs->remove('nonexistent_file.txt');
} catch (\RuntimeException $e) {
    // Log or handle error
}

Gotchas and Tips

Pitfalls

Windows vs. UNIX Path Handling:
- Issue: Path methods may incorrectly replace backslashes on UNIX systems (fixed in v8.0.9).
- Fix: Always use Path::normalize() to ensure consistency:
```
$path = Path::normalize('C:\Users\file.txt'); // Converts to forward slashes
```
Permission Denied Errors:
- Issue: Operations may fail silently or throw exceptions on restricted directories.
- Fix: Use try-catch blocks and log errors:
```
try {
    $fs->chmod('protected_file.txt', 0777);
} catch (\RuntimeException $e) {
    Log::error('Permission denied: ' . $e->getMessage());
}
```
Temp File Cleanup on Windows:
- Issue: Temp files may not delete properly on Windows (fixed in v7.1.5).
- Fix: Use Filesystem::remove() explicitly:
```
$fs->remove($tempFile);
```
Atomic Writes and Race Conditions:
- Issue: Concurrent writes to the same file can corrupt data.
- Fix: Use dumpFile() for atomic writes:
```
$fs->dumpFile('log.txt', $newContent, 0644);
```
Path Injection Risks:
- Issue: User-provided paths may lead to directory traversal attacks.
- Fix: Validate paths using Path::isAbsolute() and sanitize inputs:
```
if (!Path::isAbsolute($userInputPath)) {
    throw new \InvalidArgumentException('Invalid path');
}
```

Debugging Tips

Enable Verbose Output:
- Use Filesystem::getDebug() to log operations:
```
$fs->getDebug()->setVerbosity(Filesystem::VERBOSITY_DEBUG);
```

Check Path Normalization:

Debug path issues with:

$normalized = Path::normalize('/path/with/../segments');
dd($normalized);

Handle Windows-Specific Quirks:
- Use str_replace('\\', '/', $path) as a fallback for legacy systems:
```
$path = str_replace('\\', '/', $path);
$normalized = Path::normalize($path);
```

Extension Points

Custom Filesystem Adapter:

Extend Filesystem to add custom logic:

class CustomFilesystem extends Filesystem
{
    public function customOperation($path)
    {
        // Custom logic
    }
}

Event Listeners for File Operations:
- Use Symfony’s FilesystemEvent (if available) or wrap operations in listeners:
```
$fs->addListener('preRemove', function ($event) {
    // Log or validate before removal
});
```
Integration with Laravel Events:
- Dispatch events for critical filesystem operations:
```
event(new FilesystemOperationEvent('copy', ['source.txt', 'destination.txt']));
```

Configuration Quirks

Disable Symlinks:
- If working in restricted environments, disable symlink creation:
```
$fs = new Filesystem();
$fs->disableSymlinks();
```
Custom Temp Directory:
- Override the temp directory for testing:
```
putenv('TMPDIR=' . storage_path('framework/tests'));
```
Case-Insensitive Paths (Windows):
- Normalize paths to avoid case-sensitivity issues:
```
$normalized = Path::normalize(strtolower($path));
```

Performance Tips

Batch Operations:
- Use Filesystem::remove() with an array for multiple files:
```
$fs->remove(['file1.txt', 'file2.txt']);
```
Avoid Redundant Checks:
- Cache existence checks if paths are static:
```
if ($fs->exists($path)) {
    // Process file
}
```
Use mirror() for Large Directories:
- Efficiently replicate directory structures:
```
$fs->mirror('source_dir', 'destination_dir', null, ['override' => true]);
```

Filesystem Laravel Package