Cloud Storage Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require google/cloud-storage
   

2. Authentication (via .env or service account):

   GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
   

3. First Use Case:

   use Google\Cloud\Storage\StorageClient;
   
   $storage = new StorageClient();
   $bucket = $storage->bucket('your-bucket-name');
   
   // Upload a file
   $bucket->upload(fopen('local-file.txt', 'r'), [
       'name' => 'remote-file.txt',
       'predefinedAcl' => 'publicRead'
   ]);
   

Where to Look First

• API Docs for method signatures.
• Laravel Integration Guide for Laravel-specific patterns.
• Stream Wrapper ($storage->registerStreamWrapper()) for file_get_contents('gs://...') support.

Implementation Patterns

Core Workflows

1. File Operations

// Upload with metadata
$bucket->upload(
    fopen('file.pdf', 'r'),
    [
        'name' => 'uploads/file.pdf',
        'metadata' => ['author' => 'John Doe'],
        'cacheControl' => 'public, max-age=3600'
    ]
);

// Download to local path
$object = $bucket->object('file.pdf');
$object->downloadToFile('local-copy.pdf');

// Stream to response (Laravel)
return response()->stream(
    $object->createReadStream(),
    200,
    ['Content-Type' => 'application/pdf']
);

2. Bucket Management

// Create bucket with custom options
$bucket = $storage->createBucket('new-bucket', [
    'storageClass' => 'STANDARD',
    'location' => 'US',
    'versioning' => ['enabled' => true]
]);

// List objects with pagination
$objects = $bucket->objects(['prefix' => 'logs/']);
foreach ($objects as $object) {
    // Process each object
}

3. Signed URLs (Temporary Access)

$object = $bucket->object('private-file.pdf');
$url = $object->signedUrl(
    new \DateTime('+1 hour'),
    ['response-content-disposition' => 'attachment']
);

4. Lifecycle Rules (Soft Delete/Retention)

$bucket->update([
    'lifecycleRules' => [
        [
            'action' => ['type' => 'Delete'],
            'condition' => ['age' => 365]
        ],
        [
            'action' => ['type' => 'SetStorageClass', 'storageClass' => 'COLDLINE'],
            'condition' => ['age' => 90]
        ]
    ]
]);

Laravel Integration Tips

1. Service Provider Binding:

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton(StorageClient::class, function () {
           return new StorageClient([
               'keyFilePath' => env('GOOGLE_CREDENTIALS_PATH'),
               'projectId' => env('GOOGLE_CLOUD_PROJECT')
           ]);
       });
   }
   

2. Facade for Convenience:

   // app/Facades/CloudStorage.php
   public static function upload(string $path, string $destination, array $options = [])
   {
       return app(StorageClient::class)
           ->bucket(config('cloud-storage.bucket'))
           ->upload(fopen($path, 'r'), $options);
   }
   

3. Event Dispatching:

   // After upload
   event(new FileUploaded($object->name(), $object->metadata()));
   

4. Queue Jobs for Large Files:

   // app/Jobs/ProcessVideoUpload.php
   public function handle()
   {
       $bucket->object($this->path)->downloadToFile(storage_path('temp.mp4'));
       // Process with FFmpeg, etc.
   }
   

Gotchas and Tips

Pitfalls

1. Authentication:

   • Service Account JSON must have roles/storage.admin or equivalent.
   • Deprecated keyFile: Use keyFilePath in v1.48.4+.
   • Environment Variables: Prefer GOOGLE_APPLICATION_CREDENTIALS over hardcoding.

2. Stream Handling:

   • Resource Leaks: Always close streams or use fopen with w+ mode for writes.
   • Large Files: Use resumableUpload for files >5MB to avoid timeouts.

     $bucket->upload(
         fopen('large-file.iso', 'r'),
         ['resumable' => true]
     );
     

3. Path Traversal:

   • Sanitize Inputs: Validate name parameter in upload() to prevent ../ attacks.
   • Hierarchical Namespaces: Enable with hierarchicalNamespace: true for folder-like paths.

4. Soft Delete:

   • Objects marked for deletion are not immediately removed (retention period applies).
   • Use restore() to recover soft-deleted objects.

5. Checksum Validation:

   • CRC32C is default; override with 'checksum' => 'MD5' if needed.
   • Validate uploads with:

     $object->update(['md5Hash' => md5_file('local-file.txt')]);
     

Debugging

1. Enable Debugging:

   $storage = new StorageClient([
       'debug' => true,
       'logPath' => storage_path('logs/google-storage.log')
   ]);
   

   • Logs HTTP requests/responses to storage_path('logs/google-storage.log').

2. Common Errors:

   • InvalidArgumentException: Check bucket/object names for invalid characters.
   • Google\Cloud\Core\Exception\GoogleException: Inspect getMessage() for API-specific errors (e.g., quota limits).
   • Permission Denied: Verify IAM roles and service account permissions.

3. Retry Logic:

   • Configure retries for transient failures:

     $storage = new StorageClient([
         'retry' => [
             'maxAttempts' => 3,
             'timeout' => 30
         ]
     ]);
     

Extension Points

1. Custom Metadata:

   • Extend Google\Cloud\Storage\StorageObject to add Laravel-specific metadata:

     $object->metadata['laravel_model_id'] = $user->id;
     $bucket->updateObject($object);
     

2. Event Listeners:

   • Listen for object changes via Cloud Storage Events (Pub/Sub integration):

     // app/Providers/EventServiceProvider.php
     protected $listen = [
         'Google\Cloud\Storage\Events\ObjectFinalized' => [
             'App\Listeners\ProcessUploadedFile'
         ]
     ];
     

3. Middleware for Signed URLs:

   • Create middleware to validate signed URLs before serving:

     public function handle($request, Closure $next)
     {
         if ($request->is('storage/*')) {
             $this->validateSignedUrl($request->path());
         }
         return $next($request);
     }
     

4. Flysystem Adapter:

   • Use league/flysystem-google-cloud-storage for unified file system operations:

     $adapter = new GoogleCloudStorageAdapter($storage, 'bucket-name');
     $filesystem = new League\Flysystem\Filesystem($adapter);
     

Performance Tips

1. Parallel Uploads:

   • Use parallelUpload for multiple files:

     $bucket->parallelUpload([
         'file1.txt' => fopen('local1.txt', 'r'),
         'file2.txt' => fopen('local2.txt', 'r')
     ]);
     

2. Cache-Control Headers:

   • Set aggressive caching for static assets:

     $bucket->upload(..., [
         'cacheControl' => 'public, max-age=31536000, immutable'
     ]);
     

3. Compression:

   • Enable Gzip compression for text-based files:

     $bucket->upload(..., [
         'contentEncoding' => 'gzip'
     ]);
     

4. Batch Operations:

   • Use batch() for multiple operations (e.g., copy/move/delete):

     $batch = $bucket->batch();
     $batch->copy('source.txt', 'destination.txt');
     $batch->delete('temp.txt');
     $batch->execute();