Skip to content

Commit 69a0e7c

Browse files
marickvantuilmarickvantuil
authored
Merge pull request #145 from stackkit/4.x
4.x
2 parents 387e333 + 52452fc commit 69a0e7c

File tree

102 files changed

+1288
-7519
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

102 files changed

+1288
-7519
lines changed

‎.github/workflows/run-tests.yml

+2-11
Original file line numberDiff line numberDiff line change
@@ -67,17 +67,8 @@ jobs:
6767
- { queue: 'github-actions-laravel10-php83', laravel: '10.*', php: '8.3', 'testbench': '8.*'}
6868
- { queue: 'github-actions-laravel10-php82', laravel: '10.*', php: '8.2', 'testbench': '8.*'}
6969
- { queue: 'github-actions-laravel10-php81', laravel: '10.*', php: '8.1', 'testbench': '8.*'}
70-
- { queue: 'github-actions-laravel9-php83', laravel: '9.*', php: '8.3', 'testbench': '7.*'}
71-
- { queue: 'github-actions-laravel9-php82', laravel: '9.*', php: '8.2', 'testbench': '7.*'}
72-
- { queue: 'github-actions-laravel9-php81', laravel: '9.*', php: '8.1', 'testbench': '7.*'}
73-
- { queue: 'github-actions-laravel9-php80', laravel: '9.*', php: '8.0', 'testbench': '7.*'}
74-
- { queue: 'github-actions-laravel8-php81', laravel: '8.*', php: '8.1', 'testbench': '6.*'}
75-
- { queue: 'github-actions-laravel8-php80', laravel: '8.*', php: '8.0', 'testbench': '6.*'}
76-
- { queue: 'github-actions-laravel8-php74', laravel: '8.*', php: '7.4', 'testbench': '6.*'}
77-
- { queue: 'github-actions-laravel7-php80', laravel: '7.*', php: '8.0', 'testbench': '5.*' }
78-
- { queue: 'github-actions-laravel7-php74', laravel: '7.*', php: '7.4', 'testbench': '5.*' }
79-
- { queue: 'github-actions-laravel6-php80', laravel: '6.*', php: '8.0', 'testbench': '4.*' }
80-
- { queue: 'github-actions-laravel6-php74', laravel: '6.*', php: '7.4', 'testbench': '4.*' }
70+
- { queue: 'github-actions-laravel11-php82', laravel: '11.*', php: '8.2', 'testbench': '9.*' }
71+
- { queue: 'github-actions-laravel12-php83', laravel: '11.*', php: '8.3', 'testbench': '9.*' }
8172

8273
name: PHP ${{ matrix.payload.php }} - Laravel ${{ matrix.payload.laravel }} - DB ${{ matrix.db }}
8374

‎README.md

+105-119
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<p align="center">
2-
<img src="/assets/logo.png" width="400">
2+
<img src="/assets/logo.png" width="400">
33
</p>
44
<p align="center">
55
<img src="https://github.com/stackkit/laravel-google-cloud-tasks-queue/workflows/Run%20tests/badge.svg?branch=master" alt="Build Status">
@@ -12,161 +12,147 @@
1212
This package allows Google Cloud Tasks to be used as the queue driver.
1313

1414
<p align="center">
15-
<img src="/assets/cloud-tasks-home.png" width="100%">
15+
<img src="/assets/cloud-tasks-home.png" width="100%">
1616
</p>
1717

18-
<details>
19-
<summary>
20-
Requirements
21-
</summary>
18+
### Requirements
2219

23-
<br>
24-
This package requires Laravel 6 or higher and supports MySQL 8 and PostgreSQL 14. Might support older database versions too, but package hasn't been tested for it.
20+
This package requires Laravel 10 or 11.
2521

26-
Please check the [Laravel support policy](https://laravel.com/docs/master/releases#support-policy) table for supported Laravel and PHP versions.
27-
</details>
28-
<details>
29-
<summary>Installation</summary>
30-
<br>
31-
32-
Require the package using Composer
33-
34-
```console
35-
composer require stackkit/laravel-google-cloud-tasks-queue
36-
```
37-
38-
Add a new queue connection to `config/queue.php`
39-
40-
```php
41-
'cloudtasks' => [
42-
'driver' => 'cloudtasks',
43-
'project' => env('STACKKIT_CLOUD_TASKS_PROJECT', ''),
44-
'location' => env('STACKKIT_CLOUD_TASKS_LOCATION', ''),
45-
'queue' => env('STACKKIT_CLOUD_TASKS_QUEUE', 'default'),
46-
47-
// Required when using AppEngine
48-
'app_engine' => env('STACKKIT_APP_ENGINE_TASK', false),
49-
'app_engine_service' => env('STACKKIT_APP_ENGINE_SERVICE', ''),
50-
51-
// Required when not using AppEngine
52-
'handler' => env('STACKKIT_CLOUD_TASKS_HANDLER', ''),
53-
'service_account_email' => env('STACKKIT_CLOUD_TASKS_SERVICE_EMAIL', ''),
54-
'signed_audience' => env('STACKKIT_CLOUD_TASKS_SIGNED_AUDIENCE', true),
55-
56-
// Optional: The deadline in seconds for requests sent to the worker. If the worker
57-
// does not respond by this deadline then the request is cancelled and the attempt
58-
// is marked as a DEADLINE_EXCEEDED failure.
59-
'dispatch_deadline' => null,
60-
'backoff' => 0,
61-
],
62-
```
63-
64-
Update the `QUEUE_CONNECTION` environment variable
65-
66-
```dotenv
67-
QUEUE_CONNECTION=cloudtasks
68-
```
22+
### Installation
23+
24+
Require the package using Composer
25+
26+
```console
27+
composer require stackkit/laravel-google-cloud-tasks-queue
28+
```
29+
30+
Publish the service provider:
31+
32+
```console
33+
php artisan vendor:publish --provider=cloud-tasks
34+
```
35+
36+
Add a new queue connection to `config/queue.php`
37+
38+
```php
39+
'cloudtasks' => [
40+
'driver' => 'cloudtasks',
41+
'project' => env('CLOUD_TASKS_PROJECT', ''),
42+
'location' => env('CLOUD_TASKS_LOCATION', ''),
43+
'queue' => env('CLOUD_TASKS_QUEUE', 'default'),
44+
45+
// Required when using AppEngine
46+
'app_engine' => env('APP_ENGINE_TASK', false),
47+
'app_engine_service' => env('APP_ENGINE_SERVICE', ''),
48+
49+
// Required when not using AppEngine
50+
'handler' => env('CLOUD_TASKS_HANDLER', ''),
51+
'service_account_email' => env('CLOUD_TASKS_SERVICE_EMAIL', ''),
52+
53+
'backoff' => 0,
54+
],
55+
```
56+
57+
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`:
58+
59+
```php
60+
'disable_task_handler' => env('CLOUD_TASKS_DISABLE_TASK_HANDLER', false),
61+
```
62+
63+
Finally, change the `QUEUE_CONNECTION` to the newly defined connection.
64+
65+
```dotenv
66+
QUEUE_CONNECTION=cloudtasks
67+
```
6968

7069
Now that the package is installed, the final step is to set the correct environment variables.
7170

7271
Please check the table below on what the values mean and what their value should be.
7372

74-
| Environment variable | Description |Example
75-
---------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|---
76-
| `STACKKIT_CLOUD_TASKS_PROJECT` | The project your queue belongs to. |`my-project`
77-
| `STACKKIT_CLOUD_TASKS_LOCATION` | The region where the project is hosted. |`europe-west6`
78-
| `STACKKIT_CLOUD_TASKS_QUEUE` | The default queue a job will be added to. |`emails`
79-
| **App Engine**
80-
| `STACKKIT_APP_ENGINE_TASK` (optional) | Set to true to use App Engine task (else a Http task will be used). Defaults to false. |`true`
81-
| `STACKKIT_APP_ENGINE_SERVICE` (optional) | The App Engine service to handle the task (only if using App Engine task). |`api`
82-
| **Non- App Engine apps**
83-
| `STACKKIT_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]`
84-
| `STACKKIT_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`
85-
| `STACKKIT_CLOUD_TASKS_SIGNED_AUDIENCE` (optional) | True or false depending if you want extra security by signing the audience of your tasks. May misbehave in certain Cloud Run setups. Defaults to true. | `true`
73+
| Environment variable | Description | Example
74+
---------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------
75+
| `CLOUD_TASKS_PROJECT` | The project your queue belongs to. | `my-project`
76+
| `CLOUD_TASKS_LOCATION` | The region where the project is hosted. | `europe-west6`
77+
| `CLOUD_TASKS_QUEUE` | The default queue a job will be added to. | `emails`
78+
| **App Engine**
79+
| `APP_ENGINE_TASK` (optional) | Set to true to use App Engine task (else a Http task will be used). Defaults to false. | `true`
80+
| `APP_ENGINE_SERVICE` (optional) | The App Engine service to handle the task (only if using App Engine task). | `api`
81+
| **Non- App Engine apps**
82+
| `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]`
83+
| `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`
84+
8685
</details>
87-
<details>
88-
<summary>
89-
How it works & Differences
90-
</summary>
91-
<br>
92-
Using Cloud Tasks as a Laravel queue driver is fundamentally different than other Laravel queue drivers, like Redis.
9386

94-
Typically a Laravel queue has a worker that listens to incoming jobs using the `queue:work` / `queue:listen` command.
95-
With Cloud Tasks, this is not the case. Instead, Cloud Tasks will schedule the job for you and make an HTTP request to your application with the job payload. There is no need to run a `queue:work/listen` command.
87+
### How to
9688

97-
#### Good to know
89+
#### Passing headers to a task
9890

99-
- The "Min backoff" and "Max backoff" options in Cloud Tasks are ignored. This is intentional: Laravel has its own backoff feature (which is more powerful than what Cloud Tasks offers) and therefore I have chosen that over the Cloud Tasks one.
100-
- Similarly to the backoff feature, I have also chosen to let the package do job retries the 'Laravel way'. In Cloud Tasks, when a task throws an exception, Cloud Tasks will decide for itself when to retry the task (based on the backoff values). It will also manage its own state and knows how many times a task has been retried. This is different from Laravel. In typical Laravel queues, when a job throws an exception, the job is deleted and released back onto the queue. In order to support Laravel's backoff feature, this package must behave the same way about job retries.
91+
You can pass headers to a task by using the `setTaskHeadersUsing` method on the `CloudTasksQueue` class.
10192

102-
</details>
103-
<details>
104-
<summary>Dashboard (beta)</summary>
105-
<br>
106-
The package comes with a beautiful dashboard that can be used to monitor all queued jobs.
93+
```php
94+
use Stackkit\LaravelGoogleCloudTasksQueue\CloudTasksQueue;
10795

96+
CloudTasksQueue::setTaskHeadersUsing(static fn() => [
97+
'X-My-Header' => 'My-Value',
98+
]);
99+
```
108100

109-
<img src="/assets/dashboard.png" width="100%">
101+
If necessary, the current payload being dispatched is also available:
110102

111-
---
103+
```php
104+
use Stackkit\LaravelGoogleCloudTasksQueue\CloudTasksQueue;
112105

113-
_Experimental_
106+
CloudTasksQueue::setTaskHeadersUsing(static fn(array $payload) => [
107+
'X-My-Header' => $payload['displayName'],
108+
]);
109+
```
114110

115-
The dashboard works by storing all outgoing tasks in a database table. When Cloud Tasks calls the application and this
116-
package handles the task, we will automatically update the tasks' status, attempts
117-
and possible errors.
111+
#### Configure task handler url
118112

119-
There is probably a (small) performance penalty because each task dispatch and handling does extra database read and writes.
120-
Also, the dashboard has not been tested with high throughput queues.
113+
You can set the handler url for a task by using the `configureHandlerUrlUsing` method on the `CloudTasksQueue` class.
121114

122-
---
115+
```php
116+
use Stackkit\LaravelGoogleCloudTasksQueue\CloudTasksQueue;
123117

118+
CloudTasksQueue::configureHandlerUrlUsing(static fn() => 'https://example.com/my-url');
119+
```
124120

125-
To make use of it, enable it through the `.env` file:
121+
If necessary, the current job being dispatched is also available:
126122

127-
```dotenv
128-
STACKKIT_CLOUD_TASKS_DASHBOARD_ENABLED=true
129-
STACKKIT_CLOUD_TASKS_DASHBOARD_PASSWORD=MySecretLoginPasswordPleaseChangeThis
130-
```
123+
```php
124+
use Stackkit\LaravelGoogleCloudTasksQueue\CloudTasksQueue;
131125

132-
Then publish its assets and migrations:
126+
CloudTasksQueue::configureHandlerUrlUsing(static fn(MyJob $job) => 'https://example.com/my-url/' . $job->something());
127+
```
133128

134-
```console
135-
php artisan vendor:publish --tag=cloud-tasks
136-
php artisan migrate
137-
```
129+
### How it works and differences
138130

139-
The dashboard is accessible at the URI: /cloud-tasks
131+
Using Cloud Tasks as a Laravel queue driver is fundamentally different than other Laravel queue drivers, like Redis.
140132

141-
</details>
142-
<details>
143-
<summary>Authentication</summary>
144-
<br>
133+
Typically a Laravel queue has a worker that listens to incoming jobs using the `queue:work` / `queue:listen` command.
134+
With Cloud Tasks, this is not the case. Instead, Cloud Tasks will schedule the job for you and make an HTTP request to
135+
your application with the job payload. There is no need to run a `queue:work/listen` command.
136+
137+
#### Good to know
138+
139+
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.
140+
141+
### Authentication
145142

146143
Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable with a path to the credentials file.
147144

148145
More info: https://cloud.google.com/docs/authentication/production
149146

150-
If you're not using your master service account (which has all abilities), you must add the following roles to make it works:
147+
If you're not using your master service account (which has all abilities), you must add the following roles to make it
148+
works:
149+
151150
1. App Engine Viewer
152151
2. Cloud Tasks Enqueuer
153152
3. Cloud Tasks Viewer
154153
4. Cloud Tasks Task Deleter
155154
5. Service Account User
156-
</details>
157-
<details>
158-
<summary>Security</summary>
159-
<br>
160-
The job handler requires each request to have an OpenID token. In the installation step we set the service account email, and with that service account, Cloud Tasks will generate an OpenID token and send it along with the job payload to the handler.
161155

162-
This package verifies that the token is digitally signed by Google. Only Google Tasks will be able to call your handler.
156+
### Upgrading
163157

164-
More information about OpenID Connect:
165-
166-
https://developers.google.com/identity/protocols/oauth2/openid-connect
167-
</details>
168-
<details>
169-
<summary>Upgrading</summary>
170-
<br>
171-
Read [UPGRADING.MD](UPGRADING.md) on how to update versions.
172-
</details>
158+
Read [UPGRADING.MD](UPGRADING.md) on how to update versions.

‎UPGRADING.md

+38
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,41 @@
1+
# From 3.x to 4.x
2+
3+
## Renamed environment names (Impact: high)
4+
5+
The following environment variables have been shortened:
6+
- `STACKKIT_CLOUD_TASKS_PROJECT` → `CLOUD_TASKS_PROJECT`
7+
- `STACKKIT_CLOUD_TASKS_LOCATION` → `CLOUD_TASKS_LOCATION`
8+
- `STACKKIT_CLOUD_TASKS_QUEUE` → `CLOUD_TASKS_QUEUE`
9+
- `STACKKIT_CLOUD_TASKS_HANDLER` → `CLOUD_TASKS_HANDLER`
10+
- `STACKKIT_CLOUD_TASKS_SERVICE_EMAIL` → `CLOUD_TASKS_SERVICE_EMAIL`
11+
12+
The following environment variables have been renamed to be more consistent:
13+
14+
- `STACKKIT_APP_ENGINE_TASK` → `CLOUD_TASKS_APP_ENGINE_TASK`
15+
- `STACKKIT_APP_ENGINE_SERVICE` → `CLOUD_TASKS_APP_ENGINE_SERVICE`
16+
17+
The following environment variable has been removed:
18+
- `STACKKIT_CLOUD_TASKS_SIGNED_AUDIENCE`
19+
20+
## Removed dashboard (Impact: high)
21+
22+
The dashboard has been removed to keep the package minimal. A separate composer package might be created with an updated version of the dashboard.
23+
24+
## New configuration file (Impact: medium)
25+
26+
The configuration file has been updated to reflect the removed dashboard and to add new configurable options.
27+
28+
Please publish the new configuration file:
29+
30+
```shell
31+
php artisan vendor:publish --tag=cloud-tasks --force
32+
```
33+
34+
## Dispatch deadline (Impact: medium)
35+
36+
The `dispatch_deadline` has been removed from the task configuration. You may now use Laravel's timeout configuration to control the maximum execution time of a task.
37+
38+
139
# From 2.x to 3.x
240

341
PHP 7.2 and 7.3, and Laravel 5.x are no longer supported.

‎assets/dashboard.png

-875 KB
Binary file not shown.

‎composer.json

+9-18
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,18 @@
88
}
99
],
1010
"require": {
11+
"php": "^8.1",
1112
"ext-json": "*",
1213
"phpseclib/phpseclib": "^3.0",
13-
"google/auth": "^v1.29.1",
1414
"google/cloud-tasks": "^1.10",
1515
"thecodingmachine/safe": "^1.0|^2.0"
1616
},
1717
"require-dev": {
18-
"orchestra/testbench": "^4.0 || ^5.0 || ^6.0 || ^7.0 || ^8.0",
19-
"nunomaduro/larastan": "^1.0 || ^2.0",
18+
"orchestra/testbench": "^8.0",
2019
"thecodingmachine/phpstan-safe-rule": "^1.2",
21-
"laravel/legacy-factories": "^1.3"
20+
"laravel/legacy-factories": "^1.3",
21+
"laravel/pint": "^1.13",
22+
"larastan/larastan": "^2.9"
2223
},
2324
"autoload": {
2425
"psr-4": {
@@ -45,21 +46,11 @@
4546
"composer require laravel/framework:10.* orchestra/testbench:8.* --no-interaction --no-update",
4647
"composer update --prefer-stable --prefer-dist --no-interaction"
4748
],
48-
"l9": [
49-
"composer require laravel/framework:9.* orchestra/testbench:7.* --no-interaction --no-update",
50-
"composer update --prefer-stable --prefer-dist --no-interaction"
51-
],
52-
"l8": [
53-
"composer require laravel/framework:8.* orchestra/testbench:6.* --no-interaction --no-update",
54-
"composer update --prefer-stable --prefer-dist --no-interaction"
49+
"pint": [
50+
"pint"
5551
],
56-
"l7": [
57-
"composer require laravel/framework:7.* orchestra/testbench:5.* --no-interaction --no-update",
58-
"composer update --prefer-stable --prefer-dist --no-interaction"
59-
],
60-
"l6": [
61-
"composer require laravel/framework:6.* orchestra/testbench:4.* --no-interaction --no-update",
62-
"composer update --prefer-stable --prefer-dist --no-interaction"
52+
"larastan": [
53+
"@php -d memory_limit=-1 vendor/bin/phpstan"
6354
]
6455
}
6556
}

‎config/cloud-tasks.php

+5-4
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,9 @@
33
declare(strict_types=1);
44

55
return [
6-
'dashboard' => [
7-
'enabled' => env('STACKKIT_CLOUD_TASKS_DASHBOARD_ENABLED', false),
8-
'password' => env('STACKKIT_CLOUD_TASKS_DASHBOARD_PASSWORD', 'MyPassword1!')
9-
],
6+
// The URI of the endpoint that will handle the task
7+
'uri' => env('CLOUD_TASKS_URI', 'handle-task'),
8+
9+
// If the application only dispatches jobs
10+
'disable_task_handler' => env('CLOUD_TASKS_DISABLE_TASK_HANDLER', false),
1011
];

‎dashboard/.env.production

-1
This file was deleted.

0 commit comments

Comments
 (0)