Skip to content

Commit 3694e4e

Browse files
bshafferbshaffer
authored
fix(docs): misc docs fixes, fix troubleshooting link (#8792)
1 parent 935c543 commit 3694e4e

19 files changed

Lines changed: 481 additions & 355 deletions

‎AUTHENTICATION.md‎

Lines changed: 40 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ To review all of your authentication options see [Credential Lookup](#credential
88
For more information about authentication at Google, see [the authentication guide](https://cloud.google.com/docs/authentication).
99
Specific instructions and environment variables for each individual service are linked from the README documents listed below for each service.
1010

11-
## Credential Lookup
11+
## Application Default Credentials (ADC)
1212

1313
The Google Cloud PHP library provides several mechanisms to configure your system without providing
14-
**Service Account Credentials** directly in code.
14+
**Service Account Credentials** directly in code. These are known as Application Default Credentials.
1515

1616
**Credentials** are discovered in the following order:
1717

@@ -20,26 +20,18 @@ The Google Cloud PHP library provides several mechanisms to configure your syste
2020
3. Credentials specified in a local ADC file
2121
4. Credentials from an attached service account (for code running on Google Cloud Platform)
2222

23-
### Google Cloud Platform environments
24-
25-
While running on Google Cloud Platform environments such as Google Compute Engine, Google App Engine
26-
and Google Kubernetes Engine, no extra work is needed. The **Credentials** and are discovered
27-
automatically from the attached service account. Code should be written as if already authenticated.
28-
29-
For more information, see
30-
[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa).
31-
3223
### Environment Variables
3324

34-
**NOTE**: This library uses [`getenv`](https://www.php.net/manual/en/function.getenv.php), so if
35-
your environment variables are set in PHP, they must use
36-
[`putenv`](https://www.php.net/manual/en/function.putenv.php),
25+
The **Credentials JSON** can be placed in environment variables instead of
26+
declaring them directly in code.
3727

3828
```php
3929
putenv("GOOGLE_APPLICATION_CREDENTIALS=" . __DIR__ . '/your-credentials-file.json');
4030
```
41-
The **Credentials JSON** can be placed in environment variables instead of
42-
declaring them directly in code.
31+
32+
**NOTE**: This library uses [`getenv`](https://www.php.net/manual/en/function.getenv.php), so if
33+
your environment variables are set in PHP, they must use
34+
[`putenv`](https://www.php.net/manual/en/function.putenv.php).
4335

4436
Here are the environment variables that Google Cloud PHP checks for credentials:
4537

@@ -54,6 +46,34 @@ Note: Service account keys are a security risk if not managed correctly. You sho
5446
[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree)
5547
whenever possible.
5648

49+
### Local ADC file
50+
51+
This option allows for an easy way to authenticate in a local environment during development. If
52+
credentials are not provided in code or in environment variables, then your user credentials can be
53+
discovered from your local ADC file.
54+
55+
To set up a local ADC file:
56+
57+
1. [Download, install, and initialize the Cloud SDK](https://cloud.google.com/sdk)
58+
2. Create your local ADC file:
59+
```sh
60+
gcloud auth application-default login
61+
```
62+
63+
3. Write code as if already authenticated.
64+
65+
**NOTE:** Because this method relies on your user credentials, it is _not_ recommended for running
66+
in production.
67+
68+
### Google Cloud Platform environments
69+
70+
While running on Google Cloud Platform environments such as Google Compute Engine, Google App Engine
71+
and Google Kubernetes Engine, no extra work is needed. The **Credentials** and are discovered
72+
automatically from the attached service account. Code should be written as if already authenticated.
73+
74+
For more information, see
75+
[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa).
76+
5777
### Project ID detection
5878

5979
Some libraries support setting up the project ID via the `GOOGLE_CLOUD_PROJECT` environment variable.
@@ -72,7 +92,7 @@ The libraries that support this environment variable are:
7292
- Trace
7393
- Translate
7494

75-
### Client Authentication
95+
## Credentials Options
7696

7797
Each Google Cloud PHP client may be authenticated in code when creating a client library instance.
7898
Most clients use the `credentials` option for providing explicit credentials:
@@ -104,42 +124,17 @@ $storage = new StorageClient([
104124
'credentialsFetcher' => new ServiceAccountCredentials($scopes, $keyFile),
105125
]);
106126
```
127+
107128
A list of clients that accept these parameters are:
108129

109130
- [BigQuery](https://github.com/googleapis/google-cloud-php-bigquery)
110-
- [Datastore](https://github.com/googleapis/google-cloud-php-datastore)
111-
- [Firestore](https://github.com/googleapis/google-cloud-php-firestore)
112131
- [Logging](https://github.com/googleapis/google-cloud-php-logging)
113-
- [Spanner](https://github.com/googleapis/google-cloud-php-spanner)
114132
- [Storage](https://github.com/googleapis/google-cloud-php-storage)
115133

116134
We recommend to visit the Check the [client documentation][php-ref-docs] for the client library you're using
117135
for more in depth information.
118136
119-
### Local ADC file
120-
121-
This option allows for an easy way to authenticate in a local environment during development. If
122-
credentials are not provided in code or in environment variables, then your user credentials can be
123-
discovered from your local ADC file.
124-
125-
To set up a local ADC file:
126-
127-
1. [Download, install, and initialize the Cloud SDK](https://cloud.google.com/sdk)
128-
2. Create your local ADC file:
129-
130-
```sh
131-
gcloud auth application-default login
132-
```
133-
134-
3. Write code as if already authenticated.
135-
136-
**NOTE:** Because this method relies on your user credentials, it is _not_ recommended for running
137-
in production.
138-
139-
For more information about setting up authentication for a local development environment, see
140-
[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev).
141-
142-
### API Keys
137+
## API Keys
143138
144139
[API keys][api_keys] are a great way to quickly authenticate in a local environment during development. If
145140
you'd like to authenticate your client with API keys, use the `apiKey` client option when creating a new
@@ -170,4 +165,4 @@ If you're having trouble authenticating open a
170165
[Github Issue](https://github.com/googleapis/google-cloud-php/issues/new?title=Authentication+question)
171166
to get help. Also consider searching or asking
172167
[questions](http://stackoverflow.com/questions/tagged/google-cloud-platform+php) on
173-
[StackOverflow](http://stackoverflow.com).
168+
[StackOverflow](http://stackoverflow.com). See [Troubleshooting](DEBUG.md) for more details.

‎CLIENT_CONFIGURATION.md‎

Lines changed: 57 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -2,35 +2,12 @@
22

33
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.
44

5-
## Common Configuration Options
5+
## 1. Customizing the API Endpoint
66

7-
The following options can be passed to the constructor of any generated client (e.g., `PubSubClient`, `SpannerClient`, `StorageClient`).
7+
You can modify the API endpoint to connect to a specific Google Cloud region (to reduce latency or
8+
meet data residency requirements) or to a private endpoint (via Private Service Connect).
89

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.
10+
Some services, like Pub/Sub and Spanner, offer **regional endpoints**:
3411

3512
```php
3613
use Google\Cloud\PubSub\PubSubClient;
@@ -41,13 +18,29 @@ $pubsub = new PubSubClient([
4118
]);
4219
```
4320

44-
## 3\. Configuring a Proxy
21+
## 2. Authentication Configuration
22+
23+
While the client attempts to find [Application Default Credentials][adc] automatically, you can
24+
explicitly provide them using the `credentials` or `apiKey` options. See
25+
[`Authentication`][authentication.md] for details and examples.
26+
27+
[adc]: https://cloud.google.com/docs/authentication/application-default-credentials)
28+
[authentication.md]: https://cloud.google.com/php/docs/reference/help/authentication
29+
30+
## 3. Logging
31+
32+
Logging can be enabled using environment variables, but you can provide an explicit PSR-3 logger
33+
using the `logger` option. See [Troubleshooting](DEBUG.md) for a comprehensive guide.
34+
35+
## 3. Configuring a Proxy
4536

4637
The configuration method depends on whether you are using the `grpc` (default) or `rest` transport.
4738

4839
### Proxy with gRPC
4940

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.
41+
When using the gRPC transport, the client library respects the
42+
[standard environment variables](https://grpc.github.io/grpc/php/md_doc_environment_variables.html).
43+
You **do not** need to configure this in the PHP code itself.
5144

5245
Set the following environment variables in your shell or Docker container:
5346

@@ -56,7 +49,9 @@ export http_proxy="http://proxy.example.com:3128"
5649
export https_proxy="http://proxy.example.com:3128"
5750
```
5851

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.
52+
**Handling Self-Signed Certificates (gRPC):** If your proxy uses a self-signed certificate
53+
(Deep Packet Inspection), you cannot simply "ignore" verification in gRPC. You must provide the path
54+
to the proxy's CA certificate bundle.
6055

6156
```
6257
# Point gRPC to a CA bundle that includes your proxy's certificate
@@ -65,7 +60,9 @@ export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="/path/to/roots.pem"
6560

6661
### Proxy with REST
6762

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.
63+
If you are forcing the `rest` transport (or using a library that only supports REST), you must
64+
configure the proxy via the `transportConfig` option. This passes the settings down to the
65+
underlying Guzzle client.
6966

7067
```php
7168
use Google\Auth\HttpHandler\HttpHandlerFactory;
@@ -84,17 +81,20 @@ $secretManagerClient = new SecretManagerServiceClient([
8481
]);
8582
```
8683

87-
## 4\. Configuring Retries and Timeouts
84+
## 4. Configuring Retries and Timeouts
8885

89-
There are two ways to configure retries and timeouts: global client configuration (complex) and per-call configuration (simple).
86+
There are two ways to configure retries and timeouts: global client configuration (complex) and
87+
per-call configuration (simple).
9088

9189
### Per-Call Configuration (Recommended)
9290

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).
91+
For most use cases, it is cleaner to override settings for specific calls using
92+
`Google\ApiCore\Options\CallOptions` (or the `$optionalArgs` array in generated clients).
9493

9594
#### Available `retrySettings` Keys
9695

97-
When passing an array to `retrySettings`, you can use the following keys to fine-tune the exponential backoff strategy:
96+
When passing an array to `retrySettings`, you can use the following keys to fine-tune the
97+
exponential backoff strategy:
9898

9999
| Key | Type | Description |
100100
| ----- | ----- | ----- |
@@ -125,7 +125,9 @@ $secretManagerClient->accessSecretVersion($request, $callOptions);
125125

126126
### Disabling Retries
127127

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.
128+
You can also configure retries globally by passing a `clientConfig` array to the constructor.
129+
This is useful if you want to change the default retry strategy for *all* calls made by that client
130+
instance.
129131

130132
```php
131133
use Google\Cloud\PubSub\PubSubClient;
@@ -136,9 +138,11 @@ $pubsub = new PubSubClient([
136138
]);
137139
```
138140

139-
## 5\. Logging
141+
## 5. Logging
140142

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.
143+
You can attach any PSR-3 compliant logger (like Monolog) to debug request headers, status codes, and
144+
payloads. See [Debug Logging](https://docs.cloud.google.com/php/docs/reference/help/debug) for more
145+
examples.
142146

143147
```php
144148
use Google\Cloud\PubSub\PubSubClient;
@@ -153,3 +157,18 @@ $client = new PubSubClient([
153157
]);
154158
```
155159

160+
## 6. Other Common Configuration Options
161+
162+
The following options can be passed to the constructor of any generated client (e.g.,`PubSubClient`,
163+
`SpannerClient`, `StorageClient`).
164+
165+
| Option Key | Type | Description |
166+
| ----- | ----- | ----- |
167+
| `credentials` | `string` | `array` |
168+
| `apiKey` | `string` | An **API Key** for services that support public API key authentication (bypassing OAuth2). |
169+
| `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. |
170+
| `transport` | `string` | Specifies the transport type. Options: `'grpc'` (default), `'rest'`, or `'grpc-fallback'`. |
171+
| `transportConfig` | `array` | Configuration specific to the transport, such as gRPC channel arguments. |
172+
| `disableRetries` | `bool` | If `true`, disables the default retry logic for all methods in the client. |
173+
| `logger` | `Psr\Log\LoggerInterface` | A PSR-3 compliant logger for client-level logging and tracing. |
174+
| `universeDomain` | `string` | Overrides the default service domain (defaults to `googleapis.com`) for Cloud Universe support. |

0 commit comments

Comments
 (0)