This package allows you to use Google Cloud Tasks as the queue driver in your Laravel application.

_{Companion packages: Cloud Scheduler, Cloud Logging}

This package requires Laravel 11 or 12.

Require the package via Composer:

composer require stackkit/laravel-google-cloud-tasks-queue

Add a new queue connection to config/queue.php:

'cloudtasks' => [
  'driver' => 'cloudtasks',
  'project' => env('CLOUD_TASKS_PROJECT', ''),
  'location' => env('CLOUD_TASKS_LOCATION', ''),
  'queue' => env('CLOUD_TASKS_QUEUE', 'default'),

  // Required when using App Engine
  'app_engine'            => env('APP_ENGINE_TASK', false),
  'app_engine_service'    => env('APP_ENGINE_SERVICE', ''),

  // Required when not using App Engine
  'handler'               => env('CLOUD_TASKS_HANDLER', ''),
  'service_account_email' => env('CLOUD_TASKS_SERVICE_EMAIL', ''),

  'backoff' => 0,
  'after_commit' => false,
  // Enable this if you want to set a non-default Google Cloud Tasks dispatch timeout
  //'dispatch_deadline' => 1800, // in seconds
],

Set the appropriate environment variables:

QUEUE_CONNECTION=cloudtasks

If you're using Cloud Run:

CLOUD_TASKS_PROJECT=my-project
CLOUD_TASKS_LOCATION=europe-west6
CLOUD_TASKS_QUEUE=barbequeue
CLOUD_TASKS_SERVICE_EMAIL=[email protected]
# Optional (when using a separate task handler):
CLOUD_TASKS_SERVICE_HANDLER=

If you're using App Engine:

CLOUD_TASKS_PROJECT=my-project
CLOUD_TASKS_LOCATION=europe-west6
CLOUD_TASKS_QUEUE=barbequeue
APP_ENGINE_TASK=true
APP_ENGINE_SERVICE=my-service

Refer to the table below for descriptions of each value:

Optionally, you may publish the config file:

php artisan vendor:publish --tag=cloud-tasks

If you're using separate services for dispatching and handling tasks, and your app should only dispatch jobs (not handle them), you may disable the task handler in config/cloud-tasks.php:

'disable_task_handler' => env('CLOUD_TASKS_DISABLE_TASK_HANDLER', false),

You can pass headers to a task using the setTaskHeadersUsing method on the CloudTasksQueue class:

use Stackkit\LaravelGoogleCloudTasksQueue\CloudTasksQueue;

CloudTasksQueue::setTaskHeadersUsing(static fn() => [
  'X-My-Header' => 'My-Value',
]);

You can also access the payload being dispatched:

CloudTasksQueue::setTaskHeadersUsing(static fn(array $payload) => [
  'X-My-Header' => $payload['displayName'],
]);

Set the handler URL for a task using the configureHandlerUrlUsing method:

CloudTasksQueue::configureHandlerUrlUsing(static fn() => 'https://example.com/my-url');

Or access the job being dispatched:

CloudTasksQueue::configureHandlerUrlUsing(static fn(MyJob $job) => 'https://example.com/my-url/' . $job->something());

Customize worker options using the configureWorkerOptionsUsing method:

use Stackkit\LaravelGoogleCloudTasksQueue\IncomingTask;

CloudTasksQueue::configureWorkerOptionsUsing(function (IncomingTask $task) {
    $queueTries = [
        'high' => 5,
        'low' => 1,
    ];

    return new WorkerOptions(maxTries: $queueTries[$task->queue()] ?? 1);
});

Edit the client_options key in config/cloud-tasks.php:

'client_options' => [
    'credentials' => '/path/to/credentials.json',
]

Edit the client_options key in config/cloud-tasks.php:

'client_options' => [
    // Custom options here
]

Using Cloud Tasks as a Laravel queue driver is fundamentally different from other drivers like Redis.

With Redis or similar drivers, a worker listens for jobs via queue:work or queue:listen.
With Cloud Tasks, jobs are scheduled and dispatched via HTTP requests to your app.
There’s no need to run queue:work or queue:listen.

Cloud Tasks has its own retry configuration options like:

• Maximum number of attempts
• Retry duration
• Min/max backoff
• Max doublings

These are ignored by this package. Instead, you can configure retry behavior directly in Laravel.

If you're not using your master service account (which has all abilities), assign the following roles to your service account to make it working:

1. App Engine Viewer
2. Cloud Tasks Enqueuer
3. Cloud Tasks Viewer
4. Cloud Tasks Task Deleter
5. Service Account User

See UPGRADING.MD for instructions on updating versions.

This can occur when your application runs behind a reverse proxy.
To resolve it, add your app’s domain to Laravel’s trusted proxies.
You may need to use the wildcard *.

This seems to be a bug in PHP 8.3 and googleapis/gax-php.
See this issue for details.

A possible workaround is to disable the PHP 8.3 stack limit in php.ini:

zend.max_allowed_stack_size=-1

You can use the services defined in docker-compose.yml to run the package locally.

Inside the container:

1. Run composer install
2. Set up the environment: cp .env.example .env

Some tests use the Cloud Tasks API and require a project and credentials.
Set the appropriate variables in your .env.