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:
GAPIC-generated clients and related files | GAPIC v1
src/Google/Ads/GoogleAds/VX/Services/Gapic/ |
Post-processed clients | GAPIC v1
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.
Pattern 1 | GAPIC v1
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient(); $response = $campaignServiceClient->mutateCampaigns( $customerId, $campaignOperations ); $campaignServiceClient = $googleAdsClient->getCampaignServiceClient(); $response = $campaignServiceClient->mutateCampaigns( MutateCampaignsRequest::build( $customerId, $campaignOperations ) ); |
Pattern 2 | GAPIC v1
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.
Pattern 1 | GAPIC v1
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); $response = $googleAdsServiceClient->search( $customerId, $query, ['returnTotalResultsCount' => true] ); $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); $response = $googleAdsServiceClient->search( SearchGoogleAdsRequest::build($customerId, $query) ->setReturnTotalResultsCount(true) ); |
Pattern 2 | GAPIC v1
N/A $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); $request = (new SearchGoogleAdsRequest()) ->setCustomerId($customerId) ->setQuery($query) ->setReturnTotalResultsCount(true); $response = $googleAdsServiceClient->search($request); |
Pattern 3 | GAPIC v1
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.
Pattern 1 | GAPIC v1
$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); |
Pattern 2 | GAPIC v1
N/A $geoTargetConstantServiceClient = $googleAdsClient->getGeoTargetConstantServiceClient(); $response = $geoTargetConstantServiceClient->suggestGeoTargetConstants( new SuggestGeoTargetConstantsRequest([ 'locale' => $locale, 'country_code' => $countryCode, 'location_names' => new LocationNames(['names' => $locationNames]) ]) ); |