GAPIC

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/.

GAPIC v2 source code

Since version v20.1.0, the client library also includes a new version of GAPIC source code in src/Google/Ads/GoogleAds/vX which supports passing a request object to service clients' methods. This new version, called GAPIC v2, also serves as preparations for new features in the future. The earlier GAPIC source code, GAPIC v1, is still generated and included with each release until the end of 2023.

The Google Ads API PHP client library lets you select the version to be linked to GoogleAdsClient using the configuration setting useGapicV2Source. When this setting is set to true, the client library generates a GoogleAdsClient object that creates GAPIC v2 service clients.

Generated class locations

Here are the differences in file locations between the GAPIC versions for the two class types:

src/Google/Ads/GoogleAds/VX/Services/Gapic/

src/Google/Ads/GoogleAds/VX/Services/

src/Google/Ads/GoogleAds/VX/Services/Client/

Usage

GAPIC v1 requires you to pass each request parameter directly to a method, whereas GAPIC v2 requires you to pass a request object instead. Note that in some cases, you have more than one way of creating a request object since GAPIC v2 also generates a convenient method named build() for passing required parameters.

Example 1.1: Methods with required parameters

The following sample code compares calling CampaignService::mutate() in GAPIC v1 and v2. Note that all parameters ($customerId and $operations) are required parameters, so the build() that accepts both parameters is generated in the GAPIC v2 code.

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

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

N/A

$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 compares calling GoogleAdsServiceClient::search() in GAPIC v1 and v2. In this example, the build() that is generated in the GAPIC v2 source 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.

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['returnTotalResultsCount' => true]
);
      

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

N/A

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

N/A

$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

Compare calling GeoTargetConstantServiceClient::suggestGeoTargetConstants() in GAPIC v1 and v2. Since all parameters of GeoTargetConstantServiceClient::suggestGeoTargetConstants() are optional, build() is not generated in the GAPIC v2 source code in this case—you have to create the request object yourself.

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

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

N/A

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