Symfony Filesystem Bridge Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require bengor-file/symfony-filesystem-bridge
   

2. Basic usage:

   use BenGorFile\File\File;
   use Symfony\Component\Filesystem\Filesystem;
   
   $file = new File('/path/to/your/file.txt');
   $filesystem = new Filesystem();
   $adapter = new \BenGorFile\SymfonyFilesystemBridge\Adapter($file);
   
   // Use the adapter with Symfony Filesystem methods
   $filesystem->dumpFiles(['/target/path' => $adapter]);
   

First Use Case

Convert a BenGorFile\File object to a stream-compatible format for Symfony's Filesystem component:

$file = new File('/path/to/large-file.zip');
$adapter = new \BenGorFile\SymfonyFilesystemBridge\Adapter($file);

// Now use with Symfony's Filesystem methods
$fs = new Filesystem();
$fs->copy($adapter, '/backup/large-file.zip');

Implementation Patterns

Common Workflows

1. File Operations:

   $adapter = new \BenGorFile\SymfonyFilesystemBridge\Adapter($file);
   $fs = new Filesystem();
   
   // Copy, move, or dump files
   $fs->copy($adapter, '/destination/path');
   $fs->move($adapter, '/new/location');
   $fs->dumpFiles(['/target' => $adapter]);
   

2. Streaming Large Files:

   $adapter = new \BenGorFile\SymfonyFilesystemBridge\Adapter($file);
   $fs = new Filesystem();
   
   // Stream directly without loading into memory
   $fs->mirror('/source/dir', '/backup/dir', null, [
       'delete' => true,
       'override' => true,
       'stream' => true,
       'iterator' => new \BenGorFile\SymfonyFilesystemBridge\IteratorAdapter($adapter),
   ]);
   

3. Integration with Laravel:

   use Illuminate\Support\Facades\Storage;
   use Symfony\Component\Filesystem\Filesystem;
   
   $file = Storage::disk('s3')->getAdapter()->readStream('file.txt');
   $benGorFile = new File($file->getPathname());
   $adapter = new \BenGorFile\SymfonyFilesystemBridge\Adapter($benGorFile);
   
   $fs = new Filesystem();
   $fs->dumpFiles(['/public/uploads' => $adapter]);
   

Best Practices

• Use for Symfony Compatibility: Leverage this when you need to integrate BenGorFile\File with Symfony's Filesystem component (e.g., in Laravel projects using Symfony's filesystem utilities).
• Streaming: Prefer streaming operations (dumpFiles, mirror) for large files to avoid memory issues.
• Error Handling: Wrap operations in try-catch blocks to handle IOException or FileNotFoundException:

  try {
      $fs->copy($adapter, '/destination');
  } catch (\Symfony\Component\Filesystem\Exception\IOException $e) {
      Log::error('File operation failed: ' . $e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated Package:

   • Last release in 2017—verify compatibility with your PHP/Symfony/Laravel versions. Test thoroughly.
   • No active maintenance; fork or patch if critical bugs arise.

2. Streaming Limitations:

   • The adapter assumes the underlying BenGorFile\File supports streaming. If the file is loaded entirely into memory, streaming operations may fail or behave unexpectedly.
   • Avoid using with BenGorFile\File instances that don’t implement SeekableStreamInterface.

3. Symfony Filesystem Assumptions:

   • The adapter expects Symfony’s Filesystem to handle the actual I/O. Misconfigurations (e.g., incorrect permissions) will propagate as Symfony exceptions.

Debugging Tips

1. Check File Validity:

   if (!$adapter->isReadable()) {
       throw new \RuntimeException('File is not readable');
   }
   

2. Log Adapter State:

   \Log::debug('Adapter state:', [
       'file_path' => $adapter->getPathname(),
       'is_readable' => $adapter->isReadable(),
       'size' => $adapter->getSize(),
   ]);
   

3. Fallback for Missing Methods: If a method is missing (e.g., getMtime), implement a custom adapter extending \BenGorFile\SymfonyFilesystemBridge\Adapter:

   class CustomAdapter extends \BenGorFile\SymfonyFilesystemBridge\Adapter {
       public function getMtime() {
           return $this->file->getMtime() ?: time();
       }
   }
   

Extension Points

1. Custom Adapters: Extend the base adapter to add missing Symfony Filesystem interface methods:

   class ExtendedAdapter extends \BenGorFile\SymfonyFilesystemBridge\Adapter {
       public function getInode() {
           return $this->file->getInode() ?: 0;
       }
   }
   

2. Iterator Support: Use the provided IteratorAdapter for directory traversal:

   $iterator = new \BenGorFile\SymfonyFilesystemBridge\IteratorAdapter($directoryAdapter);
   foreach ($iterator as $fileAdapter) {
       $fs->copy($fileAdapter, '/backup/' . $fileAdapter->getFilename());
   }
   

3. Laravel Service Provider: Register the adapter as a Laravel service for global use:

   use BenGorFile\SymfonyFilesystemBridge\Adapter;
   
   public function register() {
       $this->app->bind(\BenGorFile\SymfonyFilesystemBridge\Adapter::class, function () {
           return new Adapter(new File(storage_path('app/file.txt')));
       });
   }