Basic usage

The basic usage of the client library is as follows:

use Google\Ads\GoogleAds\Lib\V22\GoogleAdsClient;
use Google\Ads\GoogleAds\Lib\V22\GoogleAdsClientBuilder;
use Google\Ads\GoogleAds\Lib\V22\GoogleAdsException;
use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\ApiCore\ApiException;

// 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
$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId(1234567890) // Replace 1234567890 with your login customer ID.
    ->build();

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

// Make calls to CampaignServiceClient.

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 various ways to instantiate it:

  • Use a google_ads_php.ini file.
  • Using environment variables.
  • Using setters on GoogleAdsClientBuilder.

Refer to the Configuration guide to learn more.

To configure a GoogleAdsClient object, create an OAuth2TokenBuilderobject and a GoogleAdsClientBuilder object and set the necessary settings:

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

// Construct a Google Ads client configured from a properties file
$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId(1234567890) // Replace 1234567890 with your login customer ID.
    ->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 previous example.

Error handling

Not every API call will succeed. 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 has details to help you figure out what went wrong:

use Google\Ads\GoogleAds\Lib\V22\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
    );
}