Cloud Storage Laravel Package

Technical Evaluation

Architecture Fit

• Strong Fit for Laravel/PHP Ecosystems: The package is idiomatic PHP and integrates seamlessly with Laravel’s Composer-based dependency management. Its PSR-compliant design aligns with Laravel’s service container and facade patterns, enabling clean integration via service providers or bindings.

  • Key Synergies:
    • Stream Wrapper (gs://) replaces storage:disk for GCS, enabling unified file I/O (e.g., Storage::put('gs://bucket/file')).
    • Predefined ACLs (e.g., publicRead) map to Laravel’s authorization layers (e.g., Gates, Policies).
    • Event-driven workflows (e.g., lifecycle hooks) can trigger Laravel queued jobs (e.g., HandleGCSUpload::dispatch()).

• Microservices & Monolith Compatibility:

  • Monoliths: Use singleton StorageClient in Laravel’s app container for shared access.
  • Microservices: Deploy as a dedicated service with gRPC/REST endpoints (e.g., GCSProxy) to abstract storage logic.

Integration Feasibility

• Laravel-Specific Levers:

  1. Service Provider Binding:

     $this->app->singleton(StorageClient::class, fn() => new StorageClient([
         'keyFile' => storage_path('service-account.json'),
         'projectId' => config('services.gcs.project_id'),
     ]));
     

  2. Facade Wrapper:

     // app/Facades/GCS.php
     public static function upload(string $path, string $bucket, array $options = []): void {
         resolve(StorageClient::class)->bucket($bucket)->upload(fopen($path, 'r'), $options);
     }
     

  3. Filesystem Adapter: Extend Laravel’s Filesystem to delegate to GCS (e.g., GcsAdapter for Storage::disk('gcs')).

• Authentication:

  • Service Accounts: Preferred for Laravel (store keyFile in config/services.php).
  • ADC (Application Default Credentials): Useful for Cloud Run/Cloud Functions (auto-injected credentials).
  • Deprecation Note: keyFile/keyFilePath are deprecated; migrate to credentials.json or environment variables.

Technical Risk

Key Questions for TPM

1. Storage Strategy:

   • Will GCS replace all Laravel storage backends (e.g., local, s3), or is it supplemental (e.g., for media)?
   • Impact: Affects migration effort and cost modeling.

2. Performance SLAs:

   • What are the latency targets for uploads/downloads (e.g., <500ms P99)?
   • Impact: May require regional buckets or CDN integration.

3. Compliance:

   • Are encryption enforcement (CMEK) or VPC Service Controls required?
   • Impact: Adds IAM complexity and key management overhead.

4. Cost Optimization:

   • Will lifecycle policies (e.g., Coldline/Archive) be automated via Laravel scheduler or Cloud Functions?
   • Impact: Reduces manual intervention but requires monitoring.

5. Disaster Recovery:

   • What is the RTO/RPO for GCS data? (e.g., multi-region replication).
   • Impact: Influences bucket location and soft-delete retention.

6. Team Skills:

   • Does the team have GCP/GCS experience, or is this a greenfield integration?
   • Impact: Affects ramp-up time and debugging velocity.

Integration Approach

Stack Fit

• Laravel Core:

  • Service Container: Inject StorageClient as a singleton or contextual binding.
  • Filesystem: Replace Illuminate\Filesystem\FilesystemAdapter with a GCS-specific adapter.
  • Queues: Use GCS events (via Pub/Sub) to trigger Laravel jobs (e.g., HandleGCSUpload::dispatch()).

• Infrastructure:

  • Compute: Works on Cloud Run, App Engine, or EC2 (with ADC).
  • Serverless: Ideal for Cloud Functions (e.g., image resizing on upload).
  • CI/CD: Test with GitHub Actions or Cloud Build (uses GCP credentials).

• Extensions:

  • Media Library: Integrate with Spatie Media Library via custom GcsAdapter.
  • Vapor: Use GCS for asset storage in Laravel Vapor deployments.

Migration Path

Compatibility

• Laravel Versions:

  • Tested: PHP 8.1+, Laravel 9.x+ (composer.json constraints).
  • Edge Cases: PHP 8.4 (explicit nullables removed; test with strict_types=1).

• GCS Features:

  • Supported: Buckets, objects, ACLs, streams, soft-delete, HNS.
  • Limited: Custom domains (requires Cloud CDN); cross-project access (IAM policies).

• Conflict Risks:

  • Stream Wrapper: May conflict with Laravel’s public/storage symlinks (use gs:// explicitly).
  • ACLs: Laravel’s chmod won’t work; use GCS predefined ACLs (e.g., publicRead).

Sequencing

1. Authentication Setup:

   • Create service account in GCP; restrict permissions (roles/storage.objectAdmin).
   • Store credentials.json in Laravel’s .env or Vault.

2. Core Integration:

   • Publish config (config/gcs.php) for bucket names, retries, and defaults.
   • Bind StorageClient in a service provider.

3. Facade/Adapter Layer:

   • Create GCS facade or extend FilesystemAdapter for Storage::disk('gcs').

4. Testing:

   • Unit Tests: Mock StorageClient (use Google\Cloud\Storage\Mock\StorageClient).
   • Integration Tests: Test with real GCS buckets (use phpunit.xml env vars).

5. Performance Tuning:

   • Benchmark parallel uploads (use Google\Cloud\Storage\Batch).
   • Configure retry policies for transient failures.

6. Monitoring:

   • Log GCS API calls (enable Google Cloud Operations Suite).
   • Set up alerts for 4xx/5xx errors (e.g., quota limits).

Operational Impact

Maintenance

• Dependencies: