The Google Ads API PHP client library provides several configuration settings that you
can use to customize the library behavior.

> [!NOTE]
> **Note:** Explicitly specified dynamic settings override settings loaded from environment variables or INI configuration files depending on the order in which builder methods are invoked.

## Configuration file

You can store most of these configuration settings in [INI](https://www.php.net/manual/en/function.parse-ini-file.php)
configuration files and use them when instantiating clients, for example,
[`google_ads_php.ini`](https://github.com/googleads/google-ads-php/blob/HEAD/examples/Authentication/google_ads_php.ini).

The credential and client builders both provide `fromFile` methods to load
settings from such files:

    $oAuth2Credential = (new OAuth2TokenBuilder())
        ->fromFile('/path/to/google_ads_php.ini')
        ->build();

    $googleAdsClient = (new GoogleAdsClientBuilder())
        ->fromFile('/path/to/google_ads_php.ini')
        ->withOAuth2Credential($oAuth2Credential)
        ->build();

If there is no configuration path provided as an argument, the `fromFile`
methods load from the default configuration path, which is:

1. The value of the environment variable named `GOOGLE_ADS_CONFIGURATION_FILE_PATH` if set.
2. Otherwise, the `google_ads_php.ini` file in your `HOME` directory.

    $oAuth2Credential = (new OAuth2TokenBuilder())
        ->fromFile()
        ->build();

    $googleAdsClient = (new GoogleAdsClientBuilder())
        ->fromFile()
        ->withOAuth2Credential($oAuth2Credential)
        ->build();

## Dynamic configuration

You can set these configuration settings dynamically when instantiating clients:

    $oAuth2Credential = (new OAuth2TokenBuilder())
        ->withClientId('INSERT_CLIENT_ID_HERE')
        ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
        ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
        ->build();

    $googleAdsClient = (new GoogleAdsClientBuilder())
        ->withOAuth2Credential($oAuth2Credential)
        ->build();

## Configuration environment variables

You can set some of the configuration settings from environment variables when
instantiating clients (see the [standard environment variables](https://developers.google.com/google-ads/api/docs/client-libs#configuration)).

The credential and client builders both provide `fromEnvironmentVariables`
methods to load settings from environment variables.

> [!NOTE]
> **Note:** Unset environment variables are *not* taken into account.

    $oAuth2Credential = (new OAuth2TokenBuilder())
        // ...
        ->fromEnvironmentVariables()
        ->build();

    $googleAdsClient = (new GoogleAdsClientBuilder())
        ->withOAuth2Credential($oAuth2Credential)
        // ...
        ->fromEnvironmentVariables()
        ->build();

## Configuration fields

> [!NOTE]
> **Note:** The fields `grpcChannelCredential`, `unaryMiddlewares`, `streamingMiddlewares`, and `grpcInterceptors` cannot be set from a configuration file or string, and can only be configured dynamically.

The configuration settings support several fields organized in categories:

1. Fields used by `OAuth2TokenBuilder`:
   - Application mode:
     - `[OAUTH2] clientId`: Your OAuth2 client ID.
     - `[OAUTH2] clientSecret`: Your OAuth2 client secret.
     - `[OAUTH2] refreshToken`: Your OAuth2 refresh token.
   - Service account mode:
     - `[OAUTH2] jsonKeyFilePath`: The JSON key path.
     - `[OAUTH2] scopes`: The OAuth2 scopes (defaults to `https://www.googleapis.com/auth/adwords` in `v32.1.0` and later; required in versions prior to `v32.1.0` or when using custom scopes; not read from an environment variable by `fromEnvironmentVariables()`).
     - `[OAUTH2] impersonatedEmail`: Optional email address to impersonate when using Google Workspace domain-wide delegation.
   - Application Default Credentials mode:
     - When neither Application mode nor Service account mode fields are set, `OAuth2TokenBuilder` automatically falls back to Application Default Credentials (ADC).
2. Fields used by `GoogleAdsClientBuilder`:
   - `[GOOGLE_ADS] loginCustomerId`: The [ID of the authorized
     customer](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) to use in the request.
   - `[GOOGLE_ADS] linkedCustomerId`: The linked customer ID.
   - `[GOOGLE_ADS] endpoint`: Optional alternative Google Ads API server endpoint.
   - `[LOGGING] logFilePath`: The path for logging output.
   - `[LOGGING] logLevel`: The logging level.
   - `[CONNECTION] proxy`: The proxy server URL used for internet connectivity.
   - `[CONNECTION] transport`: The network transport (`grpc` or `rest`).
   - `[CONNECTION] grpcChannelIsSecure`: Whether the gRPC channel is secure.
   - `[CONNECTION] grpcChannelCredential`: The gRPC channel credentials.
   - `[CONNECTION] unaryMiddlewares`: The unary middlewares.
   - `[CONNECTION] streamingMiddlewares`: The streaming middlewares.
   - `[CONNECTION] grpcInterceptors`: The gRPC interceptors.

## Configuration validation

The configuration settings are checked when instantiating clients and exceptions
are thrown when invalid. The validation rules are as follows:

1. `[OAUTH2]` fields must not be set for both Application mode and Service account mode at the same time.
2. `[OAUTH2] jsonKeyFilePath` must be set when using Service account mode (in versions prior to `v32.1.0`, `[OAUTH2] scopes` must also be set; in `v32.1.0` and later, `scopes` defaults to `https://www.googleapis.com/auth/adwords`).
3. `[OAUTH2] clientId`, `[OAUTH2] clientSecret`, and `[OAUTH2] refreshToken` must be set when using Application mode.
4. If set, `[GOOGLE_ADS] loginCustomerId` and `[GOOGLE_ADS] linkedCustomerId` must be positive numbers.
5. If set, `[CONNECTION] proxy` must be a valid URL (see the [`FILTER_VALIDATE_URL` filter](https://www.php.net/manual/en/filter.constants.php)).
6. If set, `[LOGGING] logLevel` must be a valid [PSR log level](https://github.com/php-fig/log/blob/master/src/LogLevel.php) in capital letters, such as `INFO`.
7. If set, `[CONNECTION] transport` must be either `grpc` or `rest`.
8. If `[CONNECTION] transport` is set to `grpc`, the gRPC transport must be supported by the environment (see the [Transport guide](https://developers.google.com/google-ads/api/docs/client-libs/php/transport)).
9. `[CONNECTION] grpcChannelIsSecure` must be `true` when `[CONNECTION]
   transport` is not set to `grpc` (REST connections always require HTTPS).
10. `[CONNECTION] grpcChannelCredential` can only be set when `[CONNECTION]
    transport` is set to `grpc`.
11. `[CONNECTION] grpcChannelCredential` can only be set when `[CONNECTION]
    grpcChannelIsSecure` is `true`.