Skip to content

Commit 8b4acac

Browse files
bshafferbshaffer
authored
feat(docs): add docs for core concepts, client configuration, and OCC for IAM (#8757)
1 parent 694e94a commit 8b4acac

26 files changed

Lines changed: 2336 additions & 225 deletions

‎.github/workflows/unit-tests.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,3 +98,6 @@ jobs:
9898
run: composer --no-interaction --no-ansi --no-progress update -d dev
9999
- name: Run Dev Unit Test Suite
100100
run: dev/vendor/bin/phpunit -c dev/phpunit.xml.dist
101+
- name: Run Dev Snippet Test Suite
102+
run: dev/vendor/bin/phpunit -c dev/phpunit-snippets.xml.dist
103+

‎AUTHENTICATION.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,8 @@ Each Google Cloud PHP client may be authenticated in code when creating a client
7878
Most clients use the `credentials` option for providing explicit credentials:
7979

8080
```php
81-
use Google\Cloud\VideoIntelligence\V1\VideoIntelligenceServiceClient;
81+
use Google\Cloud\VideoIntelligence\V1\Client\VideoIntelligenceServiceClient;
82+
use Google\Auth\Credentials\ServiceAccountCredentials;
8283

8384
$scope = ['https://www.googleapis.com/auth/cloud-platform'];
8485
$keyFile = json_decode(file_get_contents('/path/to/service-account.json'), true);
@@ -90,17 +91,14 @@ $video = new VideoIntelligenceServiceClient([
9091
]);
9192
```
9293

93-
#### Note:
94-
Some clients use the `credentialsFetcher` client option instead:
94+
**Note**: Some clients use the `credentialsFetcher` client option instead:
9595

9696
```php
97-
require 'vendor/autoload.php';
98-
9997
use Google\Cloud\Storage\StorageClient;
10098
use Google\Auth\Credentials\ServiceAccountCredentials;
10199

102100
// Create the service account credentials and pass them in using the "credentialsFile" option
103-
$scope = ['https://www.googleapis.com/auth/devstorage.read_only'];
101+
$scopes = ['https://www.googleapis.com/auth/devstorage.read_only'];
104102
$keyFile = json_decode(file_get_contents('/path/to/keyfile.json'), true);
105103
$storage = new StorageClient([
106104
'credentialsFetcher' => new ServiceAccountCredentials($scopes, $keyFile),

‎CLIENT_CONFIGURATION.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# Configuring Client Options for Google Cloud PHP
2+
3+
The Google Cloud PHP Client Libraries (built on `google/gax` and `google/cloud-core`) allow you to configure client behavior via an associative array passed to the client constructor. This array is processed by the [`Google\ApiCore\ClientOptions`](https://docs.cloud.google.com/php/docs/reference/gax/latest/Options.ClientOptions) class.
4+
5+
## Common Configuration Options
6+
7+
The following options can be passed to the constructor of any generated client (e.g., `PubSubClient`, `SpannerClient`, `StorageClient`).
8+
9+
| Option Key | Type | Description |
10+
| ----- | ----- | ----- |
11+
| `credentials` | `string` | `array` |
12+
| `apiKey` | `string` | An **API Key** for services that support public API key authentication (bypassing OAuth2). |
13+
| `apiEndpoint` | `string` | The address of the API remote host. specific for **Regional Endpoints** (e.g., `us-central1-pubsub.googleapis.com:443`) or Private Service Connect. |
14+
| `transport` | `string` | Specifies the transport type. Options: `'grpc'` (default), `'rest'`, or `'grpc-fallback'`. |
15+
| `transportConfig` | `array` | Configuration specific to the transport, such as gRPC channel arguments. |
16+
| `disableRetries` | `bool` | If `true`, disables the default retry logic for all methods in the client. |
17+
| `logger` | `Psr\Log\LoggerInterface` | A PSR-3 compliant logger for client-level logging and tracing. |
18+
| `universeDomain` | `string` | Overrides the default service domain (defaults to `googleapis.com`) for Cloud Universe support. |
19+
20+
## 1\. Authentication Configuration
21+
22+
While the client attempts to find "Application Default Credentials" automatically, you can explicitly provide them using
23+
the `credentials` or `apiKey` options. See [`Authentication`][authentication.md] for details and examples.
24+
25+
[authentication.md]: https://cloud.google.com/php/docs/reference/help/authentication
26+
27+
## 2\. Customizing the API Endpoint
28+
29+
You can modify the API endpoint to connect to a specific Google Cloud region (to reduce latency or meet data residency requirements) or to a private endpoint (via Private Service Connect).
30+
31+
### Connecting to a Regional Endpoint
32+
33+
Some services, like Pub/Sub and Spanner, offer regional endpoints.
34+
35+
```php
36+
use Google\Cloud\PubSub\PubSubClient;
37+
38+
$pubsub = new PubSubClient([
39+
// Connect explicitly to the us-east1 region
40+
'apiEndpoint' => 'us-east1-pubsub.googleapis.com:443',
41+
]);
42+
```
43+
44+
## 3\. Configuring a Proxy
45+
46+
The configuration method depends on whether you are using the `grpc` (default) or `rest` transport.
47+
48+
### Proxy with gRPC
49+
50+
When using the gRPC transport, the client library respects the [standard environment variables](https://grpc.github.io/grpc/php/md_doc_environment_variables.html). You **do not** need to configure this in the PHP code itself.
51+
52+
Set the following environment variables in your shell or Docker container:
53+
54+
```
55+
export http_proxy="http://proxy.example.com:3128"
56+
export https_proxy="http://proxy.example.com:3128"
57+
```
58+
59+
**Handling Self-Signed Certificates (gRPC):** If your proxy uses a self-signed certificate (Deep Packet Inspection), you cannot simply "ignore" verification in gRPC. You must provide the path to the proxy's CA certificate bundle.
60+
61+
```
62+
# Point gRPC to a CA bundle that includes your proxy's certificate
63+
export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="/path/to/roots.pem"
64+
```
65+
66+
### Proxy with REST
67+
68+
If you are forcing the `rest` transport (or using a library that only supports REST), you must configure the proxy via the `transportConfig` option. This passes the settings down to the underlying Guzzle client.
69+
70+
```php
71+
use Google\Auth\HttpHandler\HttpHandlerFactory;
72+
use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;
73+
74+
$httpClient = new GuzzleHttp\Client([
75+
// Standard Guzzle proxy configuration
76+
'proxy' => 'http://user:password@proxy.example.com',
77+
// (Optional) Disable SSL Verification (Development Only)
78+
// 'verify' => false
79+
]);
80+
$httpHandler = HttpHandlerFactory::build($httpClient);
81+
$secretManagerClient = new SecretManagerServiceClient([
82+
'transport' => 'rest',
83+
'transportConfig' => ['rest' => ['httpHandler' => [$httpHandler, 'async']]],
84+
]);
85+
```
86+
87+
## 4\. Configuring Retries and Timeouts
88+
89+
There are two ways to configure retries and timeouts: global client configuration (complex) and per-call configuration (simple).
90+
91+
### Per-Call Configuration (Recommended)
92+
93+
For most use cases, it is cleaner to override settings for specific calls using `Google\ApiCore\Options\CallOptions` (or the `$optionalArgs` array in generated clients).
94+
95+
#### Available `retrySettings` Keys
96+
97+
When passing an array to `retrySettings`, you can use the following keys to fine-tune the exponential backoff strategy:
98+
99+
| Key | Type | Description |
100+
| ----- | ----- | ----- |
101+
| `retriesEnabled` | `bool` | Enables or disables retries for this call. |
102+
| `maxRetries` | `int` | The maximum number of retry attempts. |
103+
| `initialRetryDelayMillis` | `int` | Wait time before the *first* retry (in ms). |
104+
| `retryDelayMultiplier` | `float` | Multiplier applied to the delay after each failure (e.g., `1.5`). |
105+
| `maxRetryDelayMillis` | `int` | The maximum wait time between any two retries. |
106+
| `totalTimeoutMillis` | `int` | Total time allowed for the request (including all retries) before giving up. |
107+
108+
#### Example: Advanced Backoff
109+
110+
```php
111+
// Advanced Retry Configuration
112+
$callOptions = [
113+
'retrySettings' => [
114+
'retriesEnabled' => true,
115+
'maxRetries' => 3,
116+
'initialRetryDelayMillis' => 500, // Start with 0.5s wait
117+
'retryDelayMultiplier' => 2.0, // Double the wait each time (0.5s -> 1s -> 2s)
118+
'maxRetryDelayMillis' => 5000, // Cap wait at 5s
119+
'totalTimeoutMillis' => 15000 // Max 15s total
120+
]
121+
];
122+
123+
$secretManagerClient->accessSecretVersion($request, $callOptions);
124+
```
125+
126+
### Disabling Retries
127+
128+
You can also configure retries globally by passing a `clientConfig` array to the constructor. This is useful if you want to change the default retry strategy for *all* calls made by that client instance.
129+
130+
```php
131+
use Google\Cloud\PubSub\PubSubClient;
132+
133+
$pubsub = new PubSubClient([
134+
// Quickly disable retries for the entire client
135+
'disableRetries' => true
136+
]);
137+
```
138+
139+
## 5\. Logging
140+
141+
You can attach any PSR-3 compliant logger (like Monolog) to debug request headers, status codes, and payloads. See [Debug Logging](https://docs.cloud.google.com/php/docs/reference/help/debug) for more examples.
142+
143+
```php
144+
use Google\Cloud\PubSub\PubSubClient;
145+
use Monolog\Logger;
146+
use Monolog\Handler\StreamHandler;
147+
148+
$logger = new Logger('google-cloud');
149+
$logger->pushHandler(new StreamHandler('php://stderr', Logger::DEBUG));
150+
151+
$client = new PubSubClient([
152+
'logger' => $logger
153+
]);
154+
```
155+

0 commit comments

Comments
 (0)