Filesystem Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require windwalker/filesystem ^4.0
   

   Register the service provider in config/app.php under providers:

   Windwalker\Filesystem\FilesystemServiceProvider::class,
   

2. First Use Case: Use the filesystem facade to interact with files:

   use Windwalker\Filesystem\Facades\Filesystem;
   
   // Create a file
   Filesystem::put('path/to/file.txt', 'Hello, Windwalker!');
   
   // Read a file
   $content = Filesystem::get('path/to/file.txt');
   
   // Check if a file exists
   if (Filesystem::exists('path/to/file.txt')) {
       echo "File exists!";
   }
   

3. Where to Look First:

   • Documentation
   • src/Filesystem.php for core methods.
   • src/FilesystemManager.php for managing multiple filesystem disks.

Implementation Patterns

Core Workflows

1. File Operations:

   // Write to a file
   Filesystem::put('file.txt', 'Content');
   
   // Append to a file
   Filesystem::append('file.txt', 'New content');
   
   // Delete a file
   Filesystem::delete('file.txt');
   
   // Copy/Move files
   Filesystem::copy('source.txt', 'destination.txt');
   Filesystem::move('source.txt', 'new_location.txt');
   

2. Directory Operations:

   // Create a directory
   Filesystem::makeDirectory('path/to/dir');
   
   // List directory contents
   $files = Filesystem::files('path/to/dir');
   
   // Delete a directory
   Filesystem::deleteDirectory('path/to/dir');
   

3. Filesystem Disks: Configure multiple disks (e.g., local, s3) in config/filesystems.php:

   'disks' => [
       'local' => [
           'driver' => 'local',
           'root'   => storage_path('app'),
       ],
       's3' => [
           'driver' => 's3',
           'key'    => env('AWS_ACCESS_KEY_ID'),
           'secret' => env('AWS_SECRET_ACCESS_KEY'),
           'bucket' => env('AWS_BUCKET'),
       ],
   ],
   

   Use them via the manager:

   Filesystem::disk('s3')->put('remote-file.txt', 'Remote content');
   

4. File Content Manipulation:

   // Get file contents as JSON
   $json = Filesystem::json('config.json');
   
   // Write JSON to a file
   Filesystem::json('config.json', ['key' => 'value']);
   

5. Symlinks:

   Filesystem::createSymlink('target', 'link-name');
   Filesystem::isSymlink('link-name');
   

Integration Tips

• Laravel Compatibility: Works seamlessly with Laravel’s filesystem contracts (Illuminate\Contracts\Filesystem\Filesystem).
• Custom Drivers: Extend Windwalker\Filesystem\FilesystemAdapter to create custom storage drivers.
• Events: Listen to filesystem events (e.g., filesystem.created, filesystem.deleted) via Laravel’s event system.

Gotchas and Tips

Pitfalls

1. Path Handling:

   • Always use absolute paths or ensure relative paths are resolved correctly. Windwalker follows Laravel’s filesystem conventions, so storage_path() and public_path() helpers work as expected.
   • Example:

     $path = storage_path('app/file.txt');
     Filesystem::put($path, 'Content');
     

2. Permission Issues:

   • Ensure the web server user (e.g., www-data, nginx) has write permissions for directories like storage/ and bootstrap/cache/.
   • Use Filesystem::chmod() to adjust permissions if needed:

     Filesystem::chmod('file.txt', 0644);
     

3. Driver-Specific Quirks:

   • S3/Cloud Storage: Ensure AWS/S3 credentials are correctly configured in .env. Test connections with:

     Filesystem::disk('s3')->url('file.txt'); // Throws exception if misconfigured.
     

   • FTP/SFTP: Configure timeouts and retry logic in the disk settings to avoid hangs.

4. Large File Handling:

   • For large files (>100MB), use streaming methods like Filesystem::stream() to avoid memory issues:

     Filesystem::stream('large-file.zip', function ($handle) {
         // Process the file stream
     });
     

Debugging

1. Enable Logging: Add debug logs for filesystem operations:

   Filesystem::debug(true); // Enable debug mode
   

   Check logs in storage/logs/laravel.log.

2. Check Disk Availability: Verify disks are properly configured:

   if (!Filesystem::disk('s3')->exists()) {
       throw new \RuntimeException('S3 disk is not configured.');
   }
   

3. Common Errors:

   • FileNotFoundException: Double-check paths and disk configurations.
   • PermissionException: Adjust file/directory permissions or use sudo for critical operations.
   • ConnectionException: Validate credentials and network connectivity for remote disks (e.g., S3).

Tips

1. Use Collections: Leverage Laravel’s collection methods for file operations:

   $files = collect(Filesystem::files('path/to/dir'))
       ->map(fn ($file) => Filesystem::basename($file))
       ->toArray();
   

2. Custom File Extensions: Extend the package by creating a custom adapter:

   namespace App\Filesystem;
   
   use Windwalker\Filesystem\FilesystemAdapter;
   
   class CustomAdapter extends FilesystemAdapter
   {
       public function customMethod()
       {
           // Custom logic
       }
   }
   

   Register it in config/filesystems.php:

   'custom' => [
       'driver' => 'custom',
       'class'  => App\Filesystem\CustomAdapter::class,
   ],
   

3. Performance:

   • Batch operations for multiple files:

     Filesystem::delete(['file1.txt', 'file2.txt']);
     

   • Use Filesystem::lastModified() to cache file metadata and avoid repeated checks.

4. Testing:

   • Use Laravel’s Storage facade or mock the Filesystem facade in tests:

     $this->mock(Filesystem::class)->shouldReceive('put')->once();