Weave Code
Cloud Storage Laravel Package
google/cloud-storage
Idiomatic PHP client for Google Cloud Storage. Upload/download objects, manage buckets and permissions (ACLs), use a gs:// stream wrapper, and integrate with Google Cloud PHP authentication. Great for backups, archival, and serving large files.
google/cloud-storage is an idiomatic PHP client for Google Cloud Storage, enabling reliable, global object storage for web content delivery, backups, archival, and large-file distribution. Part of the broader Google Cloud PHP suite, it provides a straightforward API to manage buckets and objects once you’ve configured authentication.
Key features:
- Upload, download, and manage objects in buckets
- Support for predefined ACLs (e.g.,
publicRead) during uploads - Built-in stream wrapper for
gs://access via standard PHP I/O - Works seamlessly with Composer and PSR-friendly workflows
- Helpful links to official API docs and debugging guidance
Frequently asked questions about Cloud Storage
- How do I integrate google/cloud-storage with Laravel’s Filesystem for unified storage (e.g., Storage::disk('gcs'))?
- Extend Laravel’s Filesystem by creating a custom adapter (e.g., `GcsAdapter`) that delegates operations to the `StorageClient`. Bind it in a service provider under `filesystems.disks.gcs` and configure it with your bucket name, credentials, and project ID. This lets you use `Storage::disk('gcs')->put('file.txt', $contents)` just like local or S3 storage.
- What’s the best way to authenticate google/cloud-storage in Laravel for production?
- Use a **service account JSON key file** stored in `config/services.php` (e.g., `'gcs' => ['key_file' => storage_path('service-account.json')]`). For serverless environments like Cloud Run, rely on **Application Default Credentials (ADC)**, which auto-injects credentials. Avoid hardcoding keys; use Laravel’s config or environment variables for rotation.
- Can I use the gs:// stream wrapper in Laravel, and how does it compare to S3’s s3://?
- Yes, register the stream wrapper via `$storage->registerStreamWrapper()` and use it like a local filesystem (e.g., `file_get_contents('gs://bucket/file.txt')`). Unlike S3’s `s3://`, GCS’s wrapper is **read-only by default** and lacks some advanced features like presigned URLs. For write operations, use the `StorageClient` directly or extend Laravel’s Filesystem.
- How do I handle large file uploads (>1GB) in Laravel with google/cloud-storage without memory issues?
- Use **chunked uploads** via `StorageClient::bucket()->upload(fopen($path, 'r'), ['resumable' => true])`. For Laravel, wrap this in a job (e.g., `UploadGCSFileJob`) to avoid timeouts. Test with files >1GB locally to validate memory usage, as PHP streams are non-blocking but may still require tuning `memory_limit` or using a queue worker.
- Does google/cloud-storage support Laravel’s queue system for async file processing (e.g., after upload)?
- Yes. Trigger Laravel jobs via **GCS event notifications** (e.g., Pub/Sub) or **lifecycle hooks**. For example, configure a Cloud Function to publish to a Pub/Sub topic on upload, then consume it in Laravel with `HandleGCSUpload::dispatch()`. Alternatively, poll for new objects using `StorageClient::bucket()->objects()` in a scheduled job.
- What Laravel versions and PHP versions does google/cloud-storage officially support?
- The package supports **PHP 8.1+** (tested up to 8.4) and works with **Laravel 9+**. For Laravel 8.x, use an older version of the SDK (e.g., `~1.25.0`). Check the [Google Cloud PHP compatibility table](https://github.com/googleapis/google-cloud-php#compatibility) for exact version mappings. Always test with your Laravel version’s strict typing if enabled.
- How do I set up CMEK (Customer-Managed Encryption Keys) for GCS in Laravel?
- Pass the **KMS key name** (e.g., `projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY`) in the `StorageClient` constructor under `encryptionKey`. Example: `$storage = new StorageClient(['encryptionKey' => config('services.gcs.kms_key')])`. Ensure your service account has `roles/cloudkms.cryptoKeyEncrypterDecrypter` permissions. Validate encryption via `StorageClient::bucket()->object()->getMetadata()`.
- Are there performance best practices for Laravel apps using google/cloud-storage in production?
- Use **regional buckets** (e.g., `us-central1`) to reduce latency. Enable **CORS** for direct client uploads if needed. For high-throughput apps, batch operations (e.g., `composer` for multiple uploads) and use **resumable uploads** for large files. Monitor latency with Cloud Monitoring and adjust bucket locations based on your user base’s geography.
- How do I handle soft-deleted files in GCS when using Laravel’s Eloquent or model events?
- GCS soft-deletes require explicit **restore tokens** (from `object()->delete()`). Store these tokens in your database alongside model IDs. In Laravel, override `deleted()` or use an observer to check for soft-deleted objects via `StorageClient::bucket()->object()->exists()` and restore them if needed. Combine with Laravel’s `SoftDeletes` trait for consistency.
- What are the alternatives to google/cloud-storage for Laravel, and when should I choose them?
- Alternatives include **AWS S3 (aws/aws-sdk-php)** for multi-cloud flexibility or **MinIO (minio/minio)** for self-hosted S3-compatible storage. Choose GCS if you’re **all-in on Google Cloud**, need **global CDN integration**, or require **advanced features like live migration**. For cost-sensitive projects, compare pricing with S3’s Standard/Intelligent-Tiering. If you need hybrid cloud, consider **Backblaze B2 (backblaze/b2)**.
Weaver
How can I help you explore Laravel packages today?