Configuration

  • The Google Ads API PHP client library offers various configuration options to customize its behavior.

  • Configuration settings can be stored in ini files or set dynamically when instantiating clients.

  • Environment variables can also be used to configure some settings.

  • Configuration settings are organized into categories and include fields for OAuth2, Google Ads specifics, logging, and connection details.

  • The library performs validation on configuration settings, throwing exceptions for invalid configurations.

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

Configuration file

You can store most of these configuration settings in INI configuration files and use them when instantiating clients, for example, 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).

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

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

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

Configuration fields

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] developerToken: (Sunset on September 9, 2026) Your Google Ads API developer token. Optional, ignored by API servers regardless of client library version, and will be rejected in a future major version of the Google Ads API.
      • v35.0.0 and later: Not required at client initialization (GoogleAdsClientBuilder removed local client-side developer token validation).
      • Versions prior to v35.0.0: Required by local client-side configuration validation.
    • [GOOGLE_ADS] loginCustomerId: The ID of the authorized customer 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. In versions prior to v35.0.0, [GOOGLE_ADS] developerToken is checked by local client-side validation (in v35.0.0 and later, [GOOGLE_ADS] developerToken is not required).
  5. If set, [GOOGLE_ADS] loginCustomerId and [GOOGLE_ADS] linkedCustomerId must be positive numbers.
  6. If set, [CONNECTION] proxy must be a valid URL (see the FILTER_VALIDATE_URL filter).
  7. If set, [LOGGING] logLevel must be a valid PSR log level in capital letters, such as INFO.
  8. If set, [CONNECTION] transport must be either grpc or rest.
  9. If [CONNECTION] transport is set to grpc, the gRPC transport must be supported by the environment (see the Transport guide).
  10. [CONNECTION] grpcChannelIsSecure must be true when [CONNECTION] transport is not set to grpc (REST connections always require HTTPS).
  11. [CONNECTION] grpcChannelCredential can only be set when [CONNECTION] transport is set to grpc.
  12. [CONNECTION] grpcChannelCredential can only be set when [CONNECTION] grpcChannelIsSecure is true.