Basic usage

The basic usage of the client library is as follows:

use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Lib\V25\GoogleAdsClientBuilder;

// Generate a refreshable OAuth 2.0 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

// Construct a Google Ads client configured from a properties file and the
// OAuth 2.0 credentials.
$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    // Replace 1234567890 with your login customer ID.
    ->withLoginCustomerId(1234567890)
    ->build();

// Create the CampaignServiceClient.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();

// Make calls to CampaignServiceClient.

Client and service initialization

To make requests to the Google Ads API, first initialize a client instance and then use it to create a service client.

Create a `GoogleAdsClient` instance

The most important class in the Google Ads API PHP library is the GoogleAdsClient class. It lets you create pre-configured service client objects that can be used for making API calls. GoogleAdsClient provides several ways to configure and instantiate it:

Use a google_ads_php.ini file.
Set environment variables.
Call setter methods on GoogleAdsClientBuilder.

Refer to the Configuration guide to learn more.

To configure a GoogleAdsClient object with explicit settings, create an OAuth2TokenBuilder object and a GoogleAdsClientBuilder object and call the appropriate setter methods:

// Generate a refreshable OAuth 2.0 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

// Construct a Google Ads client configured from explicit settings and the
// OAuth 2.0 credentials.
$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    // Replace 1234567890 with your login customer ID.
    ->withLoginCustomerId(1234567890)
    ->build();

Create a service

GoogleAdsClient provides a getter method for every service client object. For example, to create an instance of CampaignServiceClient, call the $googleAdsClient->getCampaignServiceClient() method, as shown in the preceding example.

Error handling

Not every API call succeeds. The server can throw errors if your API calls fail for some reason. It is important to capture API errors and handle them appropriately.

A GoogleAdsException instance is thrown when an API error occurs. It contains details to help you figure out what went wrong:

use Google\Ads\GoogleAds\Lib\V25\GoogleAdsException;
use Google\ApiCore\ApiException;

try {
    // Make your API call here.
} catch (GoogleAdsException $googleAdsException) {
    printf(
        "Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
        $googleAdsException->getRequestId(),
        PHP_EOL,
        PHP_EOL
    );
    foreach (
        $googleAdsException->getGoogleAdsFailure()->getErrors() as $error
    ) {
        printf(
            "\t%s: %s%s",
            $error->getErrorCode()->getErrorCode(),
            $error->getMessage(),
            PHP_EOL
        );
    }
} catch (ApiException $apiException) {
    printf(
        "ApiException was thrown with message '%s'.%s",
        $apiException->getMessage(),
        PHP_EOL
    );
}