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 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 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')
    // ...
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withDeveloperToken('INSERT_DEVELOPER_TOKEN_HERE')
    // ...
    ->build();

Configuration environment variables

You can set some of the configuration settings from environment variables when instantiating clients (see the exhaustive list).

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 file path.
      • [OAUTH2] scopes: The scopes.
      • [OAUTH2] impersonatedEmail: The email to impersonate.
  2. Fields used by GoogleAdsClientBuilder:
    • [GOOGLE_ADS] developerToken: Your developer token for accessing the API.
    • [GOOGLE_ADS] loginCustomerId: The ID of the authorized customer to use in the request.
    • [GOOGLE_ADS] linkedCustomerId: The linked customer ID.
    • [LOGGING] logFilePath: The file path for logging.
    • [LOGGING] logLevel: The logging level.
    • [CONNECTION] proxy: The proxy server URL used for internet connectivity.
    • [CONNECTION] transport: The transport.
    • [CONNECTION] grpcChannelIsSecure: Whether the gRPC channel is secure or not.
    • [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. Here are the rules:

  1. [OAUTH2] fields must not be set for both Application Mode and Service Account Mode at the same time.
  2. [OAUTH2] jsonKeyFilePath and [OAUTH2] scopes must be set when using the Service Account Mode.
  3. [OAUTH2] clientId, [OAUTH2] clientSecret and [OAUTH2] refreshToken must be set when using the Application Mode.
  4. [GOOGLE_ADS] developerToken must always be set.
  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 filter FILTER_VALIDATE_URL).
  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 guide transport).
  10. [CONNECTION] grpcChannelIsSecure must be true when [CONNECTION] transport is not set to grpc.
  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.