Laravel Gcr Worker Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require richan-fongdasen/laravel-gcr-worker
   php artisan vendor:publish --provider="RichanFongdasen\LaravelGcrWorker\GcrWorkerServiceProvider" --tag="config"
   

   Publish the config file to adjust default settings (e.g., config/gcr-worker.php).

2. Configure Environment Add Google Cloud credentials to .env:

   GCR_WORKER_PROJECT_ID=your-project-id
   GCR_WORKER_SERVICE_ACCOUNT=your-service-account@project-id.iam.gserviceaccount.com
   GCR_WORKER_REGION=us-central1
   

3. Define a Job Create a job class extending GcrWorkerJob:

   use RichanFongdasen\LaravelGcrWorker\Jobs\GcrWorkerJob;
   
   class ProcessPayment extends GcrWorkerJob
   {
       public function handle()
       {
           // Your logic here (e.g., process payment via Google Cloud Run)
       }
   }
   

4. Trigger the Job Dispatch the job via CLI or HTTP endpoint:

   php artisan gcr-worker:dispatch ProcessPayment --data='{"user_id": 123}'
   

   Or via HTTP (if configured):

   curl -X POST http://your-app.test/api/gcr-worker/process-payment
   

First Use Case: Async Task Processing

Use this package to offload CPU-intensive or long-running tasks (e.g., PDF generation, API polling) to Google Cloud Run. Example:

// In a controller or command
ProcessPayment::dispatch(['user_id' => 123, 'amount' => 100]);

The job will execute in a separate Cloud Run instance, freeing up your main app.

Implementation Patterns

1. Job Dispatch Workflows

• CLI Dispatch: Use php artisan gcr-worker:dispatch for manual testing or cron-triggered jobs.
• HTTP Endpoints: Expose a route (e.g., /api/gcr-worker/{job}) to trigger jobs via HTTP. Protect with middleware (e.g., auth:api).

  Route::post('/api/gcr-worker/{job}', [GcrWorkerController::class, 'dispatch']);
  

• Queue Integration: Chain with Laravel Queues for hybrid workflows:

  ProcessPayment::dispatch()->onQueue('gcr');
  

2. Data Handling

• Payload Serialization: Jobs accept JSON-serializable data. Use json_encode() for complex objects:

  $data = ['user' => User::find(1)->toArray()];
  ProcessPayment::dispatch($data);
  

• Environment Variables: Pass secrets via .env or inject them into the job’s handle() method.

3. Error Handling

• Retry Logic: Implement retryUntil() in your job for transient failures:

  public function retryUntil()
  {
      return now()->addMinutes(5); // Retry for 5 minutes
  }
  

• Logging: Use Laravel’s logging or Cloud Logging (via monolog):

  \Log::error('Payment failed', ['data' => $this->data]);
  

4. Configuration

• Custom Endpoints: Override the default Cloud Run URL in config/gcr-worker.php:

  'endpoint' => 'https://your-custom-url.run.app',
  

• Concurrency: Adjust max_instances in Cloud Run settings to control parallel jobs.

5. Testing

• Local Testing: Use the GcrWorkerJob facade to mock Cloud Run responses:

  $job = new ProcessPayment(['user_id' => 1]);
  $job->shouldReceive('handle')->once();
  $job->handle();
  

• Integration Tests: Test HTTP endpoints with Http::fake():

  $response = Http::post('/api/gcr-worker/process-payment');
  $response->assertStatus(202);
  

Gotchas and Tips

Pitfalls

1. Cold Starts:

   • Cloud Run instances may take 1–2 seconds to initialize. Account for this in time-sensitive workflows.
   • Fix: Use minimum instances (--min-instances=1) in Cloud Run config to keep instances warm.

2. Payload Size Limits:

   • Cloud Run has a 10MB request limit. Avoid passing large datasets directly.
   • Fix: Store data in a database or Cloud Storage and pass only IDs/references.

3. Authentication:

   • Ensure the service account has roles/run.invoker on the Cloud Run service.
   • Fix: Grant permissions via GCP Console or gcloud:

     gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
       --member="serviceAccount:YOUR_SERVICE_ACCOUNT" \
       --role="roles/run.invoker"
     

4. Job Timeouts:

   • Cloud Run defaults to 60-minute max runtime. Longer tasks may fail.
   • Fix: Increase timeout in Cloud Run settings or break tasks into smaller chunks.

5. Laravel Caching:

   • Avoid caching job results if they’re stateful (e.g., depends on external APIs).
   • Fix: Use Cache::forget() or disable caching for the job.

Debugging Tips

1. Logs:

   • Check Cloud Logging for job execution details:

     gcloud logging read "resource.type=cloud_run_revision" --limit 50
     

   • Stream logs in real-time:

     gcloud logging read "resource.type=cloud_run_revision" --limit=1 --follow
     

2. Local Debugging:

   • Use XDEBUG_CONFIG to debug Cloud Run jobs locally:

     XDEBUG_CONFIG="remote_host=host.docker.internal remote_port=9003"
     

   • Run the job locally with php artisan gcr-worker:debug.

3. Environment Mismatches:

   • Ensure .env variables match between local and Cloud Run. Use php artisan config:clear if needed.

Extension Points

1. Custom Job Middleware: Add middleware to jobs (e.g., for validation or auth):

   class ValidatePaymentData
   {
       public function handle(GcrWorkerJob $job, Closure $next)
       {
           if (empty($job->data['user_id'])) {
               throw new \InvalidArgumentException('User ID required');
           }
           return $next($job);
       }
   }
   

   Register in AppServiceProvider:

   GcrWorkerJob::addMiddleware(ValidatePaymentData::class);
   

2. Webhook Triggers: Extend the package to listen for Pub/Sub or other webhooks:

   use RichanFongdasen\LaravelGcrWorker\Jobs\WebhookJob;
   
   class HandleStripeWebhook extends WebhookJob
   {
       protected $event = 'stripe.payment_succeeded';
   }
   

3. Monitoring: Integrate with Cloud Monitoring or third-party tools (e.g., Sentry) by extending the job’s handle():

   public function handle()
   {
       try {
           // Job logic
           Sentry::captureMessage('Job completed');
       } catch (\Exception $e) {
           Sentry::captureException($e);
           throw $e;
       }
   }
   

Performance Optimizations

1. Batch Processing: Process multiple records in a single job:

   class ProcessUserPayments extends GcrWorkerJob
   {
       public function handle()
       {
           User::where('needs_payment', true)
               ->chunk(100, function ($users) {
                   foreach ($users as $user) {
                       // Process each user
                   }
               });
       }
   }
   

2. Lazy Loading: Use lazy() for large datasets to reduce memory usage:

   User::where('active', true)->lazy()->each(function ($user) {
       // Process user
   });
   

3. Cron Jobs: Schedule jobs via Cloud Scheduler + Cloud Run:

   gcloud scheduler jobs create http process-payments \
     --schedule="0 9 * * *" \
     --uri="https://your-service.run.app/api/gcr-worker/process-payments" \
     --http-method=POST