Cloud Core Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require google/cloud-core
   

   Note: This package is not used directly in application code but is a dependency for other Google Cloud PHP packages (e.g., google/cloud-storage, google/cloud-bigquery).

2. First Use Case: When integrating a Google Cloud service (e.g., Storage, BigQuery), ensure your Laravel app includes google/cloud-core as a dependency. The package handles:

   • Authentication (OAuth2, service accounts).
   • Retry logic for transient failures.
   • Request validation and error handling.

3. Where to Look First:

   • API Documentation for core utilities.
   • Debugging Guide for emulator setup and logging.
   • Service-specific packages (e.g., google/cloud-storage) for implementation examples.

Implementation Patterns

Usage Patterns

1. Authentication and Configuration:

   • Service Account Credentials:

     use Google\Cloud\Core\Grpc\CredentialsWrapper;
     $credentials = new CredentialsWrapper([
         'keyFile' => '/path/to/service-account.json',
     ]);
     

   • Environment-Based Config: Use GOOGLE_APPLICATION_CREDENTIALS or GOOGLE_CLOUD_PROJECT environment variables for Laravel’s .env:

     GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
     GOOGLE_CLOUD_PROJECT=your-project-id
     

2. Retry and Error Handling:

   • Leverage built-in retry mechanisms for transient failures (e.g., rate limits, network issues):

     use Google\Cloud\Core\Retry\RetrySettings;
     $retrySettings = new RetrySettings([
         'maxAttempts' => 3,
         'initialBackoff' => 100, // ms
     ]);
     

   • Integrate with Laravel’s exception handling (e.g., App\Exceptions\Handler) to log structured errors.

3. Debugging and Emulators:

   • Local Development: Use the Cloud Emulator to mock services (e.g., Pub/Sub, Datastore):

     gcloud beta emulators datastore start --host-port=localhost:8080
     

     Configure the emulator host in your Laravel service client:

     $client = new Google\Cloud\Datastore\DatastoreClient([
         'host' => 'localhost:8080',
     ]);
     

   • Distributed Tracing: Enable Trace v2 for microservices:

     use Google\Cloud\Core\Trace\Trace;
     Trace::enable();
     

4. Streaming and Pagination:

   • Use ObjectIterator for paginated responses (e.g., BigQuery queries):

     foreach ($queryResults as $row) {
         // Process row
     }
     

Workflows

1. Laravel Service Providers: Bind Google Cloud clients in AppServiceProvider:

   public function register()
   {
       $this->app->singleton(Google\Cloud\Storage\StorageClient::class, function ($app) {
           return new Google\Cloud\Storage\StorageClient([
               'keyFile' => config('services.google.key_file'),
           ]);
       });
   }
   

2. Artisan Commands: Use the package for CLI tasks (e.g., syncing files to GCS):

   use Google\Cloud\Storage\StorageClient;
   use Illuminate\Console\Command;
   
   class SyncFilesCommand extends Command
   {
       protected $signature = 'gcs:sync';
       public function handle(StorageClient $storage)
       {
           // Sync logic
       }
   }
   

3. Testing:

   • Mock credentials and emulators in PHPUnit:

     $this->app->instance(
         Google\Cloud\Core\Grpc\CredentialsWrapper::class,
         MockCredentials::class
     );
     

Integration Tips

• Laravel Vapor: Use the package’s retry logic to handle transient failures in serverless environments.
• Kubernetes: Configure GOOGLE_APPLICATION_CREDENTIALS as a Kubernetes secret for pod authentication.
• Horizon/Queues: Integrate Trace v2 for distributed job tracking across workers.

Gotchas and Tips

Pitfalls

1. Direct Usage:

   • Avoid: Instantiating google/cloud-core directly. It’s a dependency for other packages (e.g., google/cloud-storage).
   • Do: Use service-specific packages (e.g., google/cloud-bigquery) that rely on google/cloud-core.

2. Deprecated Options:

   • keyFile and keyFilePath are deprecated. Use credentials or environment variables instead:

     // Deprecated (avoid)
     $client = new StorageClient(['keyFile' => 'path/to/key.json']);
     
     // Recommended
     $client = new StorageClient(['credentials' => $credentialsWrapper]);
     

3. PHP Version Compatibility:

   • Ensure PHP 8.1+ for full compatibility (some features require PHP 8.4).
   • Check release notes for breaking changes (e.g., Trace v2 promotion).

4. Emulator Quirks:

   • GRPC Dependency: Emulators may require additional setup for non-GRPC clients. Use the insecure credentials wrapper for local testing:

     $client = new StorageClient(['host' => 'localhost:8080', 'useGrpc' => false]);
     

5. Retry Logic:

   • Custom retry settings may conflict with service defaults. Test in staging before production.

Debugging

1. Logging:

   • Enable debug logs for the core package:

     putenv('GOOGLE_CLOUD_DEBUG=1');
     

   • Use Laravel’s logging channel to capture structured errors:

     try {
         $client->someOperation();
     } catch (\Google\Cloud\Core\Exception\GoogleException $e) {
         \Log::error('Google Cloud Error', ['error' => $e->getMessage()]);
     }
     

2. Trace and Profiler:

   • Use Trace v2 to debug latency in microservices:

     use Google\Cloud\Core\Trace\Trace;
     Trace::enable();
     // Your code...
     $traceData = Trace::getCurrentTrace();
     

3. Validation Errors:

   • Use OptionsValidator to catch misconfigured client options early:

     use Google\Cloud\Core\ApiHelperTrait;
     $this->validateOptions($options);
     

Tips

1. Configuration:

   • Centralize Google Cloud config in config/services.php:

     'google' => [
         'key_file' => env('GOOGLE_APPLICATION_CREDENTIALS'),
         'project_id' => env('GOOGLE_CLOUD_PROJECT'),
         'retry' => [
             'max_attempts' => 3,
             'initial_backoff' => 100,
         ],
     ],
     

2. Performance:

   • Reuse client instances (e.g., StorageClient) across requests to avoid reconnecting:

     $storage = app(Google\Cloud\Storage\StorageClient::class);
     

3. Extension Points:

   • Custom Retry Logic: Extend RetrySettings for service-specific backoff strategies.
   • Middleware: Use Laravel middleware to inject credentials or trace IDs:

     public function handle($request, Closure $next)
     {
         Trace::enable();
         return $next($request);
     }
     

4. Laravel-Specific:

   • Service Container: Bind google/cloud-core dependencies as singletons for consistency:

     $this->app->singleton(CredentialsWrapper::class, function ($app) {
         return new CredentialsWrapper(['keyFile' => config('services.google.key_file')]);
     });
     

   • Envoy/Deployments: Use the package’s retry logic in deployment scripts to handle transient failures during CI/CD.