Flysystem Google Storage Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require superbalist/flysystem-google-storage:^7.2
   

   Ensure flysystem/flysystem is also installed (dependency).

2. Service Provider & Alias Register in config/app.php:

   'providers' => [
       // ...
       Superbalist\FlysystemGoogleStorage\FlysystemGoogleStorageServiceProvider::class,
   ],
   'aliases' => [
       // ...
       'GoogleStorage' => Superbalist\FlysystemGoogleStorage\Facades\GoogleStorage::class,
   ],
   

3. Configuration Publish the config:

   php artisan vendor:publish --provider="Superbalist\FlysystemGoogleStorage\FlysystemGoogleStorageServiceProvider"
   

   Update .env with Google Cloud credentials:

   GOOGLE_STORAGE_BUCKET=your-bucket-name
   GOOGLE_STORAGE_KEY=your-service-account-key.json
   GOOGLE_STORAGE_PROJECT_ID=your-project-id
   

4. First Use Case: Upload a File

   use Superbalist\FlysystemGoogleStorage\Facades\GoogleStorage;
   
   $file = GoogleStorage::put('path/to/file.txt', fopen('local-file.txt', 'r+'));
   

Implementation Patterns

Core Workflows

1. File Operations

   • Upload: Use put() with a stream or file path.

     $file = GoogleStorage::put('remote/path/file.jpg', fopen('local.jpg', 'r+'));
     

   • Download: Use read() or get().

     $contents = GoogleStorage::read('remote/path/file.jpg');
     GoogleStorage::get('remote/path/file.jpg', 'local-copy.jpg');
     

   • Delete: Use delete().

     GoogleStorage::delete('remote/path/file.jpg');
     

2. Directory Handling

   • Create: Use mkdir().

     GoogleStorage::mkdir('remote/folder');
     

   • List Contents: Use listContents().

     $files = GoogleStorage::listContents('remote/folder', true);
     

3. Symlinks & Metadata

   • Symlinks: Use createSymlink().

     GoogleStorage::createSymlink('target-path', 'link-path');
     

   • Metadata: Use getMetadata()/setMetadata().

     $metadata = GoogleStorage::getMetadata('remote/path/file.jpg');
     GoogleStorage::setMetadata('remote/path/file.jpg', ['customKey' => 'value']);
     

New Features (v7.2.2)

1. RFC3986 Compliant URLs Generate properly encoded URLs for sharing files:

   $url = GoogleStorage::url('path/to/file.jpg');
   // Returns RFC3986 compliant URL (e.g., https://storage.googleapis.com/bucket/path%2Fto%2Ffile.jpg)
   

2. Temporary (Signed) URLs Generate time-limited URLs for secure access:

   $signedUrl = GoogleStorage::temporaryUrl('path/to/file.jpg', now()->addHours(1));
   // Returns a signed URL valid for 1 hour
   

Integration with Laravel

1. Filesystem Integration Configure filesystems.php to use the adapter:

   'disks' => [
       'gcs' => [
           'driver' => 'google',
           'bucket' => env('GOOGLE_STORAGE_BUCKET'),
           'key' => env('GOOGLE_STORAGE_KEY'),
           'project_id' => env('GOOGLE_STORAGE_PROJECT_ID'),
           'root' => env('GOOGLE_STORAGE_ROOT', ''),
           'url' => env('GOOGLE_STORAGE_URL', null), // Optional: Custom base URL
       ],
   ],
   

   Use via Laravel’s Storage facade:

   Storage::disk('gcs')->put('file.txt', 'contents');
   

2. Queueing File Uploads Offload heavy uploads to queues:

   use Illuminate\Support\Facades\Queue;
   use Superbalist\FlysystemGoogleStorage\Facades\GoogleStorage;
   
   Queue::push(function () {
       GoogleStorage::put('large-file.zip', fopen('local-large.zip', 'r+'));
   });
   

3. Presigned URLs (Legacy) For backward compatibility, use the adapter directly:

   $url = GoogleStorage::getAdapter()->getClient()->buildPresignedUrl(
       'https://storage.googleapis.com/your-bucket/file.jpg',
       3600 // 1 hour
   );
   

Gotchas and Tips

Common Pitfalls

1. Credentials & Permissions

   • Ensure the service account key has:
     • storage.objects.create
     • storage.objects.delete
     • storage.objects.update
     • storage.objects.list
   • Tip: Use gcloud auth application-default login for local testing.

2. Path Handling

   • Google Storage paths are case-sensitive. Avoid uppercase letters in paths.
   • Trailing slashes (/) matter. Use rtrim() if needed:

     $path = rtrim($path, '/');
     

3. Large Files

   • For files > 5MB, use resumable uploads (not directly supported by this adapter). Consider:
     • Chunking the file manually.
     • Using Google’s client library directly for large files.

4. URL Generation

   • RFC3986 Compliance: The url() method now returns properly encoded URLs. Avoid manual URL encoding.
   • Signed URLs: Temporary URLs expire. Cache them if needed or regenerate dynamically.

5. Deprecation Note

   • Last major update was in 2019, but v7.2.2 introduces new features.
   • Tip: Monitor for future compatibility issues with newer Google Cloud SDKs.

Debugging Tips

1. Enable Debugging Configure the Google client to log requests:

   $client = GoogleStorage::getAdapter()->getClient();
   $client->setScopes([...]);
   $client->setAuthConfig(env('GOOGLE_STORAGE_KEY'));
   $client->setUseBatch(true); // For batch operations
   

2. Check HTTP Errors Wrap operations in try-catch:

   try {
       GoogleStorage::put('file.txt', 'contents');
   } catch (\Google\Cloud\Storage\StorageException $e) {
       \Log::error('Google Storage Error: ' . $e->getMessage());
   }
   

3. Verify Bucket Exists Ensure the bucket exists before operations:

   $buckets = GoogleStorage::getAdapter()->getClient()->bucketList();
   $bucketExists = false;
   foreach ($buckets as $bucket) {
       if ($bucket->name() === env('GOOGLE_STORAGE_BUCKET')) {
           $bucketExists = true;
           break;
       }
   }
   

Extension Points

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

   $adapter = GoogleStorage::getAdapter();
   $adapter->setCustomMetadata('key', 'value');
   

2. Event Listeners Listen for file operations via Laravel events:

   Storage::disk('gcs')->put('file.txt', 'contents');
   // Trigger custom logic after upload.
   

3. Fallback to Local Storage Implement a fallback disk in filesystems.php:

   'disks' => [
       'gcs' => [
           'driver' => 'google',
           // ... config ...
       ],
       'fallback' => [
           'driver' => 'local',
           'root' => storage_path('app/fallback'),
       ],
   ],
   

   Use in code:

   $disk = Storage::disk(env('USE_GCS') ? 'gcs' : 'fallback');
   

4. Custom URL Generation Override the url() method for custom domains:

   $adapter = GoogleStorage::getAdapter();
   $adapter->setCustomDomain('cdn.yourdomain.com');
   $url = GoogleStorage::url('path/to/file.jpg');