GAPIC

AI-generated Key Takeaways

• The Google Ads API PHP client library source code is primarily generated using the GAPIC Generator based on published proto files, with manual modifications for integration.

• Service clients are located in src/Google/Ads/GoogleAds/VX/Services/Client/.

• To use a client, you create a request object and pass it, and there are often multiple ways to create request objects depending on required and optional parameters.

• For methods with required parameters, a build() method is generated, while for methods with only optional parameters, you must manually create the request object.

The source code in the src/Google/Ads/GoogleAds/vX directory of the Google Ads API PHP client library, where X is the Google Ads API version, is automatically generated using the GAPIC (Generated API Client) Generator, based on the published proto files.

The generated source code is then modified to contain references to traits and classes required to create the service clients that works with the Google Ads API using the GoogleAdsClient class, which is created by calling GoogleAdsClientBuilder::build(). Both GoogleAdsClient and GoogleAdsClientBuilder are manually created classes located in src/Google/Ads/GoogleAds/Lib/vX/.

Generated class locations

The post-processed service clients are located in src/Google/Ads/GoogleAds/VX/Services/Client/.

Usage

You must create a request object and pass it to the client you want to use. In some cases, you have more than one way of creating a request object because some clients also have a convenient method named build() for passing required parameters.

Example 1.1: Methods with required parameters

The following sample code shows how to call CampaignService::mutate(). All parameters ($customerId and $operations) are required parameters, so the build() that accepts both parameters is generated in the code.

Pattern 1

$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
      $customerId,
      $campaignOperations
    )
);

Pattern 2

$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

Example 1.2: Methods with required parameters and optional parameters

The following sample code calls GoogleAdsServiceClient::search(). In this example, the build() that is generated in the code accepts only two parameters ($customerId and $query) because they're required parameters. To request the total number of results that match the query ignoring the LIMIT clause, you have to set it explicitly using setReturnTotalResultsCount(). Alternatively, you can pass all the parameters together to the constructor of SearchGoogleAdsRequest, as shown in pattern 3.

Pattern 1

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);

Pattern 2

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);

Pattern 3

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'return_total_results_count' => true
]);
$response = $googleAdsServiceClient->search($request);

Example 2: Methods with only optional parameters

This example shows how to call GeoTargetConstantServiceClient::suggestGeoTargetConstants(). Since all parameters of GeoTargetConstantServiceClient::suggestGeoTargetConstants() are optional, build() is not generated in the source code in this case—you have to create the request object yourself.

Pattern 1

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);

Pattern 2

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);