Laravel Google Cloud Tasks Queue Laravel Package

Getting Started

This package lets you use Google Cloud Tasks as a Laravel queue driver, replacing (or supplementing) Redis/SQS/database. Jobs are pushed to Cloud Tasks, which then calls back into your app over HTTP; your app executes the job inside that request instead of a long-running queue:work daemon.

Minimal setup:

1. composer require stackkit/laravel-google-cloud-tasks-queue
2. Create a queue in GCP first — gcloud tasks queues create default --location=europe-west1 — the queue must exist before dispatching or you'll get a 404 from the API.
3. Add a connection to config/queue.php:

   'google-cloud-tasks' => [
       'driver'      => 'google-cloud-tasks',
       'project'     => env('GOOGLE_CLOUD_PROJECT'),
       'location'    => env('GOOGLE_CLOUD_TASKS_LOCATION'),
       'queue'       => env('GOOGLE_CLOUD_TASKS_QUEUE', 'default'),
       'credentials' => env('GOOGLE_APPLICATION_CREDENTIALS'),
       'handler'     => '/queues/google-cloud-tasks',
   ],
   

4. Set QUEUE_CONNECTION=google-cloud-tasks.
5. Register the callback route in AppServiceProvider::boot() (or override it from config) — the package exposes a helper on its queue class, e.g. GoogleCloudTasksQueue::route('/queues/google-cloud-tasks'). It registers a route outside your web middleware group and handles CSRF/signature checks for you.

First use case: a SendWelcomeEmail job dispatched after signup, where the HTTP request should return fast and the email send should not block it. Dispatch as usual (SendWelcomeEmail::dispatch($user)), confirm the task appears in the GCP console, and confirm your local handler endpoint receives the push.

Where to look first: the connection config block, the handler route registration, and the GCP console's task logs — that's where 90% of issues surface.

Implementation Patterns

Standard dispatch stays identical. Job::dispatch(), dispatch()->delay(now()->addMinutes(10)), onQueue('emails'), chains, and batches all work. onQueue() maps directly to a Cloud Tasks queue name, so your queue names in GCP must match what you pass to onQueue().

Delays are first-class. Cloud Tasks' native scheduling makes delay()/later() genuinely useful and cheap — good for reminders, trial-expiry nudges, retry-with-backoff flows, and "check if webhook arrived in 5 minutes" polling.

Integration tip: return fast, offload heavy work. The job runs inside the Cloud Tasks HTTP request. For anything over ~30s, either use the package's ability to re-dispatch onto a different connection, or split into a small "kickoff" job plus real workers. A common pattern is Cloud Tasks → thin HTTP job → push to a worker-backed queue for the heavy lifting.

Per-job tuning. Set maxAttempts, maxBackoff, minBackoff, and maxDoublings on the job/queue to control Cloud Tasks' exponential backoff, and dispatchDeadline for the request timeout. Tune these per job type rather than globally — a webhook retry wants tight backoff, an email send wants loose.

Local development. Cloud Tasks can't reach localhost. Options: point the connection at sync locally, use a tunnel (ngrok/cloudflared/Laravel Herd expose) and set handler to the public URL, or use a GCP emulator. Guard the handler route so it's only registered where the driver is used.

Multi-environment. Use separate GCP projects/queues per environment, and inject the handler base URL via config so staging tasks never hit production. Keep GOOGLE_APPLICATION_CREDENTIALS out of the repo; on GCP runtimes prefer the attached service account.

Observability. Log X-CloudTasks-TaskName and X-CloudTasks-TaskRetryCount from the incoming request headers in your job's handle() so retries are traceable across Laravel logs and GCP task logs.

Gotchas and Tips

• Payload size limit (100 KB). Serialized job payloads are sent in the HTTP body. Large Eloquent models with eager-loaded relations blow past this. Pass IDs and re-query in handle().
• No queue:work daemon. Running php artisan queue:work against this connection does nothing useful; the HTTP callback is the worker. Don't rely on queue:restart or worker-timeouts for these jobs.
• failed_jobs is written by Laravel, retries are driven by GCP. When your handler returns a non-2xx the task is retried by Cloud Tasks, not by Laravel's worker. Make sure the job returns the right status — a swallowed exception in handle() counts as success and the task is deleted.
• Queues must pre-exist. No auto-creation. Provision queues (and IAM for the service account: cloudtasks.enqueuer, plus roles/run.invoker or equivalent if using OIDC-authenticated handlers) in Terraform/gcloud as part of deploy.
• Handler route must bypass CSRF and auth middleware. The package registers it outside web, but if you write your own handler or add global middleware (e.g. VerifyCsrfToken globals, IP allowlists) you'll get 419/403 and silent retry storms.
• Secure the endpoint. Anyone who can reach the handler can execute jobs. Use Cloud Tasks OIDC tokens with service_account_email, or the package's signature verification, and don't expose the route publicly without one.
• dispatch_deadline caps at 30 minutes, and task schedule-out is limited to ~30 days. Anything longer needs a different design.
• deleteWhenMissingModels matters more here. A retried task after a model delete will otherwise fail repeatedly until maxAttempts.
• Time zone/config caching. After changing queue config, run php artisan config:cache — stale cached config pointing at the wrong GCP project is a classic silent failure.
• Upgrading to v6.0.0: this is a Laravel 13 compatibility release. Check composer.json constraints before upgrading — a major bump typically drops older Laravel versions, so confirm your framework version and PHP minimum, run your queue test suite in staging, and verify the credentials/handler config keys haven't been renamed. Jobs serialized before the upgrade may not deserialize, so drain pending tasks before deploying.
• Local debugging: set the connection's log/HTTP client options high, and inspect outbound requests with Http::fake()-style assertions in tests — this is the fastest way to catch malformed handler URLs and missing queue names.