Skip to content

Commit 609894c

Browse files
nick-zhnick-zh
authored
update doc (#10)
1 parent b33f9d1 commit 609894c

10 files changed

+185
-1
lines changed

Diff for: ‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,4 @@ Run the Hugo docker image to verify your changes
1313
```bash
1414
docker-compose up
1515
```
16-
Visit `http://localhost:1313/php-simple-kafka-client.github.io7` in your browser.
16+
Visit `http://localhost:1313/php-simple-kafka-client.github.io/` in your browser.

Diff for: ‎content/configuration/setOAuthBearerTokenRefreshCb.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: "setOAuthBearerTokenRefreshCb"
3+
date: 2021-09-07T10:09:37+01:00
4+
draft: false
5+
geekdocCollapseSection: true
6+
---
7+
## Description
8+
```php
9+
public function setOAuthBearerTokenRefreshCb(callable $callback): void {}
10+
```
11+
The SASL/OAUTHBEARER token refresh callback is triggered automatically or via `poll`
12+
whenever OAUTHBEARER is the SASL mechanism and a token needs to be retrieved,
13+
typically based on the configuration defined in `sasl.oauthbearer.config`.
14+
15+
The callback should invoke `setOauthBearerToken`
16+
or `setOauthBearerTokenFailure` to indicate success
17+
or failure, respectively.
18+
## Example
19+
```php
20+
$conf = new SimpleKafkaClient\Configuration();
21+
$conf->set('metadata.broker.list', getenv('TEST_KAFKA_BROKERS'));
22+
$conf->set('security.protocol', 'SASL_PLAINTEXT');
23+
$conf->set('sasl.mechanisms', 'OAUTHBEARER');
24+
$conf->set('sasl.oauthbearer.config', 'principalClaimName=azp');
25+
$conf->setOAuthBearerTokenRefreshCb(function($kafka, $oAuthBearerConfig) {
26+
// get the refresh token with some custom code, then act accordingly
27+
if ($tokenRefreshWasSucessful) {
28+
$kafka->setOAuthBearerToken($token, $lifetimeMs, $principalName, $extensions);
29+
} else {
30+
$kafka->setOAuthBearerTokenFailure($errorReason);
31+
}
32+
});
33+
```

Diff for: ‎content/consumer/setOAuthBearerToken.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: "setOauthBearerToken"
3+
date: 2021-09-07T10:09:37+01:00
4+
draft: false
5+
---
6+
## Description
7+
```php
8+
public function setOAuthBearerToken(string $token, int $lifetimeMs, string $principalName, ?array $extensions = null): void {}
9+
```
10+
The SASL/OAUTHBEARER token refresh callback or event handler should invoke
11+
this method upon success. The extension keys must not include the reserved
12+
key `auth`, and all extension keys and values must conform to the required
13+
format as per https://tools.ietf.org/html/rfc7628#section-3.1
14+
## Example
15+
```php
16+
$conf = new SimpleKafkaClient\Configuration();
17+
$conf->set('metadata.broker.list', getenv('TEST_KAFKA_BROKERS'));
18+
$conf->set('security.protocol', 'SASL_PLAINTEXT');
19+
$conf->set('sasl.mechanisms', 'OAUTHBEARER');
20+
$conf->set('sasl.oauthbearer.config', 'principalClaimName=azp');
21+
$conf->setOAuthBearerTokenRefreshCb(function($kafka, $oAuthBearerConfig) {
22+
// get the refresh token with some custom code, then act accordingly
23+
if ($tokenRefreshWasSucessful) {
24+
$kafka->setOAuthBearerToken($token, $lifetimeMs, $principalName, $extensions);
25+
} else {
26+
$kafka->setOAuthBearerTokenFailure($errorReason);
27+
}
28+
});
29+
```

Diff for: ‎content/consumer/setOAuthBearerTokenFailure.md

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: "setOauthBearerTokenFailure"
3+
date: 2021-09-07T10:09:37+01:00
4+
draft: false
5+
---
6+
## Description
7+
```php
8+
public function setOauthBearerTokenFailure(string $errorString): void {}
9+
```
10+
The SASL/OAUTHBEARER token refresh callback or event handler should invoke
11+
this method upon failure. `$errorString` should be a human readable error reason
12+
why acquiring a token failed.
13+
## Example
14+
```php
15+
$conf = new SimpleKafkaClient\Configuration();
16+
$conf->set('metadata.broker.list', getenv('TEST_KAFKA_BROKERS'));
17+
$conf->set('security.protocol', 'SASL_PLAINTEXT');
18+
$conf->set('sasl.mechanisms', 'OAUTHBEARER');
19+
$conf->set('sasl.oauthbearer.config', 'principalClaimName=azp');
20+
$conf->setOAuthBearerTokenRefreshCb(function($kafka, $oAuthBearerConfig) {
21+
// get the refresh token with some custom code, then act accordingly
22+
if ($tokenRefreshWasSucessful) {
23+
$kafka->setOAuthBearerToken($token, $lifetimeMs, $principalName, $extensions);
24+
} else {
25+
$kafka->setOAuthBearerTokenFailure($errorReason);
26+
}
27+
});
28+
```

Diff for: ‎content/producer/setOAuthBearerToken.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: "setOauthBearerToken"
3+
date: 2021-09-07T10:09:37+01:00
4+
draft: false
5+
---
6+
## Description
7+
```php
8+
public function setOAuthBearerToken(string $token, int $lifetimeMs, string $principalName, ?array $extensions = null): void {}
9+
```
10+
The SASL/OAUTHBEARER token refresh callback or event handler should invoke
11+
this method upon success. The extension keys must not include the reserved
12+
key `auth`, and all extension keys and values must conform to the required
13+
format as per https://tools.ietf.org/html/rfc7628#section-3.1
14+
## Example
15+
```php
16+
$conf = new SimpleKafkaClient\Configuration();
17+
$conf->set('metadata.broker.list', getenv('TEST_KAFKA_BROKERS'));
18+
$conf->set('security.protocol', 'SASL_PLAINTEXT');
19+
$conf->set('sasl.mechanisms', 'OAUTHBEARER');
20+
$conf->set('sasl.oauthbearer.config', 'principalClaimName=azp');
21+
$conf->setOAuthBearerTokenRefreshCb(function($kafka, $oAuthBearerConfig) {
22+
// get the refresh token with some custom code, then act accordingly
23+
if ($tokenRefreshWasSucessful) {
24+
$kafka->setOAuthBearerToken($token, $lifetimeMs, $principalName, $extensions);
25+
} else {
26+
$kafka->setOAuthBearerTokenFailure($errorReason);
27+
}
28+
});
29+
```

Diff for: ‎content/producer/setOAuthBearerTokenFailure.md

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: "setOauthBearerTokenFailure"
3+
date: 2021-09-07T10:09:37+01:00
4+
draft: false
5+
---
6+
## Description
7+
```php
8+
public function setOauthBearerTokenFailure(string $errorString): void {}
9+
```
10+
The SASL/OAUTHBEARER token refresh callback or event handler should invoke
11+
this method upon failure. `$errorString` should be a human readable error reason
12+
why acquiring a token failed.
13+
## Example
14+
```php
15+
$conf = new SimpleKafkaClient\Configuration();
16+
$conf->set('metadata.broker.list', getenv('TEST_KAFKA_BROKERS'));
17+
$conf->set('security.protocol', 'SASL_PLAINTEXT');
18+
$conf->set('sasl.mechanisms', 'OAUTHBEARER');
19+
$conf->set('sasl.oauthbearer.config', 'principalClaimName=azp');
20+
$conf->setOAuthBearerTokenRefreshCb(function($kafka, $oAuthBearerConfig) {
21+
// get the refresh token with some custom code, then act accordingly
22+
if ($tokenRefreshWasSucessful) {
23+
$kafka->setOAuthBearerToken($token, $lifetimeMs, $principalName, $extensions);
24+
} else {
25+
$kafka->setOAuthBearerTokenFailure($errorReason);
26+
}
27+
});
28+
```

Diff for: ‎content/whats-new/release-0.1.1.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: "Release v0.1.1"
3+
date: 2020-12-27T22:09:37+01:00
4+
draft: false
5+
---
6+
Bugfixes:
7+
- fix Consumer:assign argument type
8+
- fix Producer:getTopicHandle return type
9+

Diff for: ‎content/whats-new/release-0.1.2.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: "Release v0.1.2"
3+
date: 2020-12-27T22:09:37+01:00
4+
draft: false
5+
---
6+
Bugfixes:
7+
- fix version and some tests
8+
- fix Windows build
9+

Diff for: ‎content/whats-new/release-0.1.3.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: "Release v0.1.3"
3+
date: 2020-12-27T22:09:37+01:00
4+
draft: false
5+
---
6+
Features
7+
- support oauthbearer mechanism
8+
9+
Bugfixes:
10+
- fixes for PHP8.1
11+
- fix Windows build
12+

Diff for: ‎content/whats-new/release-0.1.4.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: "Release v0.1.4"
3+
date: 2020-12-27T22:09:37+01:00
4+
draft: false
5+
---
6+
Bugfixes:
7+
- fixes for PHP8.1

0 commit comments

Comments
 (0)