Flysystem Rackspace Laravel Package

Getting Started

Minimal Steps

1. Install the Package

   composer require league/flysystem-rackspace
   

   Ensure league/flysystem is installed (required dependency).

2. Configure Laravel Filesystem Add to config/filesystems.php:

   'disks' => [
       'rackspace' => [
           'driver' => 'custom',
           'adapter' => League\Flysystem\Rackspace\RackspaceAdapter::class,
           'options' => [
               'username' => env('RACKSPACE_USERNAME'),
               'apiKey'   => env('RACKSPACE_API_KEY'),
               'region'   => env('RACKSPACE_REGION', 'IAD'),
               'container' => env('RACKSPACE_CONTAINER'),
           ],
       ],
   ],
   

3. Bind to Laravel Storage In AppServiceProvider@boot():

   Storage::extend('rackspace', function ($app) {
       $config = config('filesystems.disks.rackspace');
       $adapter = new League\Flysystem\Rackspace\RackspaceAdapter(
           $config['options']['username'],
           $config['options']['apiKey'],
           $config['options']['region'],
           $config['options']['container']
       );
       return Storage::build([
           'driver' => 'league-flysystem',
           'adapter' => $adapter,
       ]);
   });
   

4. First Use Case: Upload and Retrieve

   // Upload
   Storage::disk('rackspace')->put('file.txt', 'Hello Rackspace!');
   
   // Download
   $contents = Storage::disk('rackspace')->get('file.txt');
   

Implementation Patterns

Core Usage Patterns

1. Basic CRUD Operations

   // Upload from string
   Storage::disk('rackspace')->put('file.txt', 'Content');
   
   // Upload from file path
   Storage::disk('rackspace')->putFile('folder', '/local/path/file.txt');
   
   // Download to string
   $content = Storage::disk('rackspace')->get('file.txt');
   
   // Download to file
   Storage::disk('rackspace')->download('file.txt', '/local/path/download.txt');
   
   // Delete
   Storage::disk('rackspace')->delete('file.txt');
   

2. Directory Operations

   // List contents (handles pagination for >10K files)
   $files = Storage::disk('rackspace')->files();
   $directories = Storage::disk('rackspace')->directories();
   
   // Create directory
   Storage::disk('rackspace')->makeDirectory('folder');
   
   // Delete directory (recursively)
   Storage::disk('rackspace')->deleteDirectory('folder');
   

3. Metadata Handling

   // Get file metadata
   $metadata = Storage::disk('rackspace')->metadata('file.txt');
   
   // Update metadata (if supported by Rackspace)
   Storage::disk('rackspace')->updateMetadata('file.txt', ['customKey' => 'value']);
   

4. Streaming Large Files

   // Stream upload
   $stream = fopen('/local/large-file.zip', 'r');
   Storage::disk('rackspace')->writeStream('large-file.zip', $stream);
   fclose($stream);
   
   // Stream download
   $stream = Storage::disk('rackspace')->readStream('large-file.zip');
   file_put_contents('/local/download.zip', $stream);
   

Integration Tips

1. Laravel Facade Usage Leverage Laravel’s Storage facade for consistency:

   // Upload user avatar
   $path = $request->file('avatar')->store('avatars', 'rackspace');
   
   // Generate shared URL (if needed, requires Rackspace SDK)
   $url = Storage::disk('rackspace')->getAdapter()->getClient()->getObjectUrl(...);
   

2. Service Layer Abstraction Create a service to encapsulate Rackspace logic:

   class RackspaceStorageService {
       protected $disk;
   
       public function __construct() {
           $this->disk = Storage::disk('rackspace');
       }
   
       public function uploadUserMedia($userId, $file) {
           $path = "users/{$userId}/{$file->hashName()}";
           return $this->disk->putFileAs('public', $file, $path);
       }
   }
   

3. Fallback Mechanism Implement a fallback to local storage:

   try {
       return Storage::disk('rackspace')->get($path);
   } catch (\Exception $e) {
       return Storage::disk('local')->get($path);
   }
   

4. Event-Based Workflows Use Laravel events for post-upload actions:

   Storage::disk('rackspace')->put($path, $content);
   event(new FileUploaded($path, 'rackspace'));
   

5. Configuration Management Centralize credentials in .env:

   RACKSPACE_USERNAME=your_username
   RACKSPACE_API_KEY=your_api_key
   RACKSPACE_REGION=IAD
   RACKSPACE_CONTAINER=your_container
   

Gotchas and Tips

Common Pitfalls

1. API Version Mismatch

   • Issue: Rackspace Cloud Files v1 is deprecated. The package may fail with v2 endpoints.
   • Fix: Verify your Rackspace account uses Cloud Files v1 or fork the package for v2 support.

2. 10,000-File Limit

   • Issue: listContents() defaults to a 10,000-file limit. The package fixes this, but large directories may still require manual pagination.
   • Fix: Use listContents() with custom markers for deep pagination:

     $files = [];
     $marker = null;
     do {
         $contents = Storage::disk('rackspace')->listContents($marker);
         $files = array_merge($files, $contents);
         $marker = end($contents)->path();
     } while ($marker);
     

3. Credential Handling

   • Issue: Hardcoded credentials or leaks in logs.
   • Fix: Use Laravel’s .env and never log sensitive data:

     \Log::debug('Using Rackspace container: ' . env('RACKSPACE_CONTAINER'));
     

4. PHP Version Conflicts

   • Issue: Package requires PHP 5.3+, but Laravel 8+ needs PHP 8.x.
   • Fix: Use a compatibility layer or fork the package:

     // Add to composer.json
     "config": {
         "platform": {
             "php": "7.4"
         }
     }
     

5. Connection Timeouts

   • Issue: Slow responses or timeouts with large files.
   • Fix: Increase timeout in Rackspace SDK config:

     $adapter = new RackspaceAdapter([...], [
         'timeout' => 60,
     ]);
     

Debugging Tips

1. Enable Verbose Logging

   $adapter = new RackspaceAdapter([...]);
   $adapter->getClient()->setDebug(true);
   

2. Inspect Raw API Responses

   $client = Storage::disk('rackspace')->getAdapter()->getClient();
   $response = $client->listObjects();
   \Log::debug($response->getBody());
   

3. Test with Minimal Buckets

   • Use a small test container to avoid hitting rate limits or storage quotas.

4. Check for Deprecated Methods

   • The package may use outdated Flysystem methods. Update calls if needed:

     // Old (may not work)
     $filesystem->read('file');
     
     // New
     $filesystem->readStream('file')->getContents();
     

Extension Points

1. Custom Metadata Handling Extend the adapter to support custom metadata:

   class ExtendedRackspaceAdapter extends League\Flysystem\Rackspace\RackspaceAdapter {
       public function setCustomMetadata($path, array $metadata) {
           $object = $this->getClient()->getObject($this->container, $path);
           $object->setMetadata($metadata);
           $object->update();
       }
   }
   

2. Shared Links Generation Add shared URL generation (requires Rackspace SDK):

   $adapter = new RackspaceAdapter([...]);
   $client = $adapter->getClient();
   $url = $client->getObjectUrl($container, $path, ['expires' => time() + 3600]);
   

3. Event Dispatching Wrap the adapter to dispatch events:

   class EventfulRackspaceAdapter extends League\Flysystem\Rackspace\RackspaceAdapter {
       public function write($path, $contents, Config $config) {
           event(new FileUploading($path, $contents));
           parent::write($path, $contents, $config);
           event(new FileUploaded($path));
       }
   }
   

4. Fallback to Local Storage Implement a hybrid