Skip to content

Commit d0e96ff

Browse files
muath-yemuath-ye
authored
Update README.md
1 parent fd76179 commit d0e96ff

File tree

1 file changed

+74
-69
lines changed

1 file changed

+74
-69
lines changed

‎README.md

+74-69
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Cloud Tasks queue driver for Laravel
1+
# Cloud Tasks Queue Driver for Laravel
22

3-
[![Run tests](https://github.com/stackkit/laravel-google-cloud-tasks-queue/actions/workflows/run-tests.yml/badge.svg)](https://github.com/stackkit/laravel-google-cloud-tasks-queue/actions/workflows/run-tests.yml)
4-
<a href="https://packagist.org/packages/stackkit/laravel-google-cloud-tasks-queue"><img src="https://poser.pugx.org/stackkit/laravel-google-cloud-tasks-queue/v/stable.svg" alt="Latest Stable Version"></a>
3+
[![Run tests](https://github.com/stackkit/laravel-google-cloud-tasks-queue/actions/workflows/run-tests.yml/badge.svg)](https://github.com/stackkit/laravel-google-cloud-tasks-queue/actions/workflows/run-tests.yml)
4+
<a href="https://packagist.org/packages/stackkit/laravel-google-cloud-tasks-queue"><img src="https://poser.pugx.org/stackkit/laravel-google-cloud-tasks-queue/v/stable.svg" alt="Latest Stable Version"></a>
55
<a href="https://packagist.org/packages/stackkit/laravel-google-cloud-tasks-queue"><img src="https://poser.pugx.org/stackkit/laravel-google-cloud-tasks-queue/downloads.svg" alt="Downloads"></a>
66

7-
This package allows Google Cloud Tasks to be used as the queue driver.
7+
This package allows you to use Google Cloud Tasks as the queue driver in your Laravel application.
88

99
<sub>Companion packages: <a href="https://github.com/stackkit/laravel-google-cloud-scheduler">Cloud Scheduler</a>, <a href="https://github.com/marickvantuil/laravel-google-cloud-logging">Cloud Logging</a></sub>
1010

@@ -18,37 +18,37 @@ This package requires Laravel 11 or 12.
1818

1919
### Installation
2020

21-
Require the package using Composer
21+
Require the package via Composer:
2222

2323
```shell
2424
composer require stackkit/laravel-google-cloud-tasks-queue
2525
```
2626

27-
Add a new queue connection to `config/queue.php`
27+
Add a new queue connection to `config/queue.php`:
2828

2929
```php
3030
'cloudtasks' => [
3131
'driver' => 'cloudtasks',
3232
'project' => env('CLOUD_TASKS_PROJECT', ''),
3333
'location' => env('CLOUD_TASKS_LOCATION', ''),
3434
'queue' => env('CLOUD_TASKS_QUEUE', 'default'),
35-
36-
// Required when using AppEngine
35+
36+
// Required when using App Engine
3737
'app_engine' => env('APP_ENGINE_TASK', false),
3838
'app_engine_service' => env('APP_ENGINE_SERVICE', ''),
39-
40-
// Required when not using AppEngine
39+
40+
// Required when not using App Engine
4141
'handler' => env('CLOUD_TASKS_HANDLER', ''),
4242
'service_account_email' => env('CLOUD_TASKS_SERVICE_EMAIL', ''),
43-
43+
4444
'backoff' => 0,
4545
'after_commit' => false,
46-
// enable this if you want to set a non-default Google Cloud Tasks dispatch timeout
46+
// Enable this if you want to set a non-default Google Cloud Tasks dispatch timeout
4747
//'dispatch_deadline' => 1800, // in seconds
4848
],
4949
```
5050

51-
Finally, set the correct environment variables.
51+
Set the appropriate environment variables:
5252

5353
```dotenv
5454
QUEUE_CONNECTION=cloudtasks
@@ -61,7 +61,7 @@ CLOUD_TASKS_PROJECT=my-project
6161
CLOUD_TASKS_LOCATION=europe-west6
6262
CLOUD_TASKS_QUEUE=barbequeue
6363
CLOUD_TASKS_SERVICE_EMAIL=my-service-account@appspot.gserviceaccount.com
64-
# Optionally (when using a separate task handler):
64+
# Optional (when using a separate task handler):
6565
CLOUD_TASKS_SERVICE_HANDLER=
6666
```
6767

@@ -75,39 +75,39 @@ APP_ENGINE_TASK=true
7575
APP_ENGINE_SERVICE=my-service
7676
```
7777

78-
Please check the table below on what the values mean and what their value should be.
78+
Refer to the table below for descriptions of each value:
7979

80-
| Environment variable | Description | Example
81-
---------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------
82-
| `CLOUD_TASKS_PROJECT` | The project your queue belongs to. | `my-project`
83-
| `CLOUD_TASKS_LOCATION` | The region where the project is hosted. | `europe-west6`
84-
| `CLOUD_TASKS_QUEUE` | The default queue a job will be added to. | `emails`
85-
| **App Engine**
86-
| `APP_ENGINE_TASK` (optional) | Set to true to use App Engine task (else a Http task will be used). Defaults to false. | `true`
87-
| `APP_ENGINE_SERVICE` (optional) | The App Engine service to handle the task (only if using App Engine task). | `api`
88-
| **Non- App Engine apps**
89-
| `CLOUD_TASKS_SERVICE_EMAIL` (optional) | The email address of the service account. Important, it should have the correct roles. See the section below which roles. | `[email protected]`
90-
| `CLOUD_TASKS_HANDLER` (optional) | The URL that Cloud Tasks will call to process a job. This should be the URL to your Laravel app. By default we will use the URL that dispatched the job. | `https://<your website>.com`
80+
| Environment Variable | Description | Example |
81+
|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|
82+
| `CLOUD_TASKS_PROJECT` | The project your queue belongs to. | `my-project` |
83+
| `CLOUD_TASKS_LOCATION` | The region where the project is hosted. | `europe-west6` |
84+
| `CLOUD_TASKS_QUEUE` | The default queue to which a job will be added. | `emails` |
85+
| **App Engine** | | |
86+
| `APP_ENGINE_TASK` (optional) | Set to true to use an App Engine task (otherwise an HTTP task will be used). Defaults to false. | `true` |
87+
| `APP_ENGINE_SERVICE` (optional) | The App Engine service that will handle the task (only if using App Engine tasks). | `api` |
88+
| **Non-App Engine Apps** | | |
89+
| `CLOUD_TASKS_SERVICE_EMAIL` (optional) | The service account's email address. It must have the required roles (see below). | `[email protected]` |
90+
| `CLOUD_TASKS_HANDLER` (optional) | The URL that Cloud Tasks will call to process a job. Should point to your Laravel app. Defaults to the URL that dispatched the job. | `https://<your-website>.com` |
9191

92-
</details>
92+
---
9393

9494
Optionally, you may publish the config file:
9595

9696
```console
9797
php artisan vendor:publish --tag=cloud-tasks
9898
```
9999

100-
If you are using separate services for dispatching and handling tasks, and your application only dispatches jobs and should not be able to handle jobs, you may disable the task handler from `config/cloud-tasks.php`:
100+
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`:
101101

102102
```php
103103
'disable_task_handler' => env('CLOUD_TASKS_DISABLE_TASK_HANDLER', false),
104104
```
105105

106-
### How to
106+
### How-To
107107

108-
#### Passing headers to a task
108+
#### Pass headers to a task
109109

110-
You can pass headers to a task by using the `setTaskHeadersUsing` method on the `CloudTasksQueue` class.
110+
You can pass headers to a task using the `setTaskHeadersUsing` method on the `CloudTasksQueue` class:
111111

112112
```php
113113
use Stackkit\LaravelGoogleCloudTasksQueue\CloudTasksQueue;
@@ -117,37 +117,31 @@ CloudTasksQueue::setTaskHeadersUsing(static fn() => [
117117
]);
118118
```
119119

120-
If necessary, the current payload being dispatched is also available:
120+
You can also access the payload being dispatched:
121121

122122
```php
123-
use Stackkit\LaravelGoogleCloudTasksQueue\CloudTasksQueue;
124-
125123
CloudTasksQueue::setTaskHeadersUsing(static fn(array $payload) => [
126124
'X-My-Header' => $payload['displayName'],
127125
]);
128126
```
129127

130-
#### Configure task handler url
128+
#### Configure the task handler URL
131129

132-
You can set the handler url for a task by using the `configureHandlerUrlUsing` method on the `CloudTasksQueue` class.
130+
Set the handler URL for a task using the `configureHandlerUrlUsing` method:
133131

134132
```php
135-
use Stackkit\LaravelGoogleCloudTasksQueue\CloudTasksQueue;
136-
137133
CloudTasksQueue::configureHandlerUrlUsing(static fn() => 'https://example.com/my-url');
138134
```
139135

140-
If necessary, the current job being dispatched is also available:
136+
Or access the job being dispatched:
141137

142138
```php
143-
use Stackkit\LaravelGoogleCloudTasksQueue\CloudTasksQueue;
144-
145139
CloudTasksQueue::configureHandlerUrlUsing(static fn(MyJob $job) => 'https://example.com/my-url/' . $job->something());
146140
```
147141

148142
#### Configure worker options
149143

150-
You can configure worker options by using the `configureWorkerOptionsUsing` method on the `CloudTasksQueue` class.
144+
Customize worker options using the `configureWorkerOptionsUsing` method:
151145

152146
```php
153147
use Stackkit\LaravelGoogleCloudTasksQueue\IncomingTask;
@@ -164,7 +158,7 @@ CloudTasksQueue::configureWorkerOptionsUsing(function (IncomingTask $task) {
164158

165159
#### Use a custom credentials file
166160

167-
Modify (or add) the `client_options` key in the `config/cloud-tasks.php` file:
161+
Edit the `client_options` key in `config/cloud-tasks.php`:
168162

169163
```php
170164
'client_options' => [
@@ -175,63 +169,74 @@ Modify (or add) the `client_options` key in the `config/cloud-tasks.php` file:
175169

176170
#### Modify CloudTasksClient options
177171

178-
Modify (or add) the `client_options` key in the `config/cloud-tasks.php` file:
172+
Edit the `client_options` key in `config/cloud-tasks.php`:
179173

180174
```php
181175
'client_options' => [
182-
// custom options here
176+
// Custom options here
183177
]
184178
```
185179

186-
### How it works and differences
180+
### How it works & differences
181+
182+
Using Cloud Tasks as a Laravel queue driver is fundamentally different from other drivers like Redis.
183+
184+
With Redis or similar drivers, a worker listens for jobs via `queue:work` or `queue:listen`.
185+
With Cloud Tasks, jobs are scheduled and dispatched via HTTP requests to your app.
186+
There’s no need to run `queue:work` or `queue:listen`.
187187

188-
Using Cloud Tasks as a Laravel queue driver is fundamentally different than other Laravel queue drivers, like Redis.
188+
### Good to Know
189189

190-
Typically a Laravel queue has a worker that listens to incoming jobs using the `queue:work` / `queue:listen` command.
191-
With Cloud Tasks, this is not the case. Instead, Cloud Tasks will schedule the job for you and make an HTTP request to
192-
your application with the job payload. There is no need to run a `queue:work/listen` command.
190+
Cloud Tasks has its own retry configuration options like:
193191

194-
#### Good to know
192+
- Maximum number of attempts
193+
- Retry duration
194+
- Min/max backoff
195+
- Max doublings
195196

196-
Cloud Tasks has it's own retry configuration options: maximum number of attempts, retry duration, min/max backoff and max doublings. All of these options are ignored by this package. Instead, you may configure max attempts, retry duration and backoff strategy right from Laravel.
197+
These are ignored by this package. Instead, you can configure retry behavior directly in Laravel.
197198

198199
### Authentication
199200

200-
If you're not using your master service account (which has all abilities), you must add the following roles to make it
201-
works:
201+
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:
202202

203-
1. App Engine Viewer
204-
2. Cloud Tasks Enqueuer
205-
3. Cloud Tasks Viewer
206-
4. Cloud Tasks Task Deleter
203+
1. App Engine Viewer
204+
2. Cloud Tasks Enqueuer
205+
3. Cloud Tasks Viewer
206+
4. Cloud Tasks Task Deleter
207207
5. Service Account User
208208

209209
### Upgrading
210210

211-
Read [UPGRADING.MD](UPGRADING.md) on how to update versions.
211+
See [UPGRADING.MD](UPGRADING.md) for instructions on updating versions.
212212

213213
### Troubleshooting
214214

215-
#### HttpRequest.url must start with 'https://'
215+
#### `HttpRequest.url` must start with `https://`
216216

217-
This can happen when your application runs behind a reverse proxy. To fix this, add the application domain to Laravel's [trusted proxies](https://laravel.com/docs/11.x/requests#trusting-all-proxies). You may need to add the wildcard `*` as trusted proxy.
217+
This can occur when your application runs behind a reverse proxy.
218+
To resolve it, add your app’s domain to Laravel’s [trusted proxies](https://laravel.com/docs/11.x/requests#trusting-all-proxies).
219+
You may need to use the wildcard `*`.
218220

219-
#### Maximum call stack size (zend.max_allowed_stack_size - zend.reserved_stack_size) reached. Infinite recursion?
221+
#### `Maximum call stack size (zend.max_allowed_stack_size - zend.reserved_stack_size) reached. Infinite recursion?`
220222

221-
This currently seems to be a bug with PHP 8.3 and `googleapis/gax-php`. See [this issue](https://github.com/googleapis/gax-php/issues/584) for more information.
223+
This seems to be a bug in PHP 8.3 and `googleapis/gax-php`.
224+
See [this issue](https://github.com/googleapis/gax-php/issues/584) for details.
222225

223-
A potential workaround is to disable PHP 8.3 call stack limit by setting this value in `php.ini`:
226+
A possible workaround is to disable the PHP 8.3 stack limit in `php.ini`:
224227

225228
```ini
226-
zend.max_allowed_stack_size: -1
229+
zend.max_allowed_stack_size=-1
227230
```
228231

229232
### Contributing
230233

231-
You can use the services defined in `docker-compose.yml` to start running the package.
234+
You can use the services defined in `docker-compose.yml` to run the package locally.
232235

233-
Inside the container, run `composer install`.
236+
Inside the container:
234237

235-
Set up the environment: `cp .env.example .env`
238+
1. Run `composer install`
239+
2. Set up the environment: `cp .env.example .env`
236240

237-
Some tests hit the Cloud Tasks API and need a project and key to be able to hit it. See the variables in `.env`
241+
Some tests use the Cloud Tasks API and require a project and credentials.
242+
Set the appropriate variables in your `.env`.

0 commit comments

Comments
 (0)