File Storage Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require anglemx/file-storage-bundle
   

2. Configure the Bundle Add the bundle to config/bundles.php:

   return [
       // ...
       Angle\FileStorageBundle\AngleFileStorageBundle::class => ['all' => true],
   ];
   

3. Define Storage Backend Configure in config/packages/angle_file_storage.yaml (or .env):

   angle_file_storage:
       type: local
       container: "uploads"
   

   For AWS S3 or Azure Blob Storage, replace type and add required credentials.

4. First Use Case: Uploading a File Inject the FileStorage service and use it:

   use Angle\FileStorageBundle\Service\FileStorage;
   
   public function uploadFile(FileStorage $storage)
   {
       $filePath = $storage->upload('path/to/local/file.txt', 'destination/file.txt');
       return $filePath;
   }
   

Implementation Patterns

Core Workflows

1. File Operations

   • Upload: $storage->upload($localPath, $remotePath)
   • Download: $storage->download($remotePath, $localPath)
   • Delete: $storage->delete($remotePath)
   • Exists: $storage->exists($remotePath)

2. Streaming Large Files Use uploadStream() and downloadStream() for memory efficiency:

   $storage->uploadStream($stream, 'large-file.zip');
   

3. Dynamic Backend Switching Override the type in config or via environment variables for different environments (e.g., local for dev, aws_s3 for prod).

4. Integration with Symfony Components

   • Event Dispatching: Extend with FileStorageEvents (e.g., FileUploadedEvent).
   • Dependency Injection: Bind FileStorage to a custom interface for testing:

     services:
         App\Service\CustomStorage:
             arguments:
                 $storage: '@angle_file_storage.file_storage'
     

5. Presigned URLs (AWS S3) Generate temporary URLs for secure downloads:

   $url = $storage->getPresignedUrl('file.txt', '+1 hour');
   

Best Practices

• Path Handling: Use relative paths for local storage to avoid hardcoding absolute paths.
• Error Handling: Wrap operations in try-catch blocks (e.g., StorageException).
• Testing: Mock FileStorage in unit tests using PHPUnit’s createMock():

  $mockStorage = $this->createMock(FileStorage::class);
  $mockStorage->method('upload')->willReturn('mocked/path');
  

Gotchas and Tips

Pitfalls

1. Azure Blob Storage Validation

   • Commands like azure:list will fail if the service is misconfigured. Validate credentials first:

     php bin/console angle:file-storage:validate
     

2. Local Path Resolution

   • Relative paths (e.g., uploads) are resolved relative to var/. Use absolute paths for clarity:

     container: "/var/www/uploads"  # Absolute path
     

3. AWS SDK Dependencies

   • Ensure aws/aws-sdk-php is installed and configured. Conflicts may arise with other AWS SDK versions.

4. Permission Issues

   • Local storage requires write permissions on the var/ directory. Set:

     chmod -R 775 var/
     

5. Environment Variables

   • Avoid hardcoding secrets. Use .env and validate with:

     php bin/console debug:container angle_file_storage
     

Debugging Tips

• Log Storage Operations: Enable Symfony’s profiler to trace file operations.
• Check Backend-Specific Errors:
  • AWS: Verify aws_region, username, and secret in the AWS console.
  • Azure: Test connection with az storage blob list (Azure CLI).

Extension Points

1. Custom Backends Extend Angle\FileStorageBundle\Service\StorageInterface to add support for Google Cloud Storage or FTP.

2. Event Subscribers Listen for FileUploadedEvent to trigger notifications or metadata updates:

   use Angle\FileStorageBundle\Event\FileUploadedEvent;
   
   public static function getSubscribedEvents()
   {
       return [
           FileUploadedEvent::NAME => 'onFileUploaded',
       ];
   }
   

3. Configuration Overrides Dynamically switch backends per request using middleware:

   $storage->setType('aws_s3'); // Override for specific requests
   

4. Symfony Cache Integration Cache presigned URLs or metadata to reduce backend calls:

   $this->cache->get('presigned_url_' . $filePath, function() use ($storage) {
       return $storage->getPresignedUrl($filePath);
   });
   

Configuration Quirks

• Null Values: Fields like aws_region or secret can be null for local storage but are required for cloud backends.
• Container Naming: Ensure AWS S3/Azure container names are globally unique (for S3) or valid per Azure tenant.