GAPIC

Page Summary

outlined_flag

• 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 number, 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 work with the Google Ads API using the GoogleAdsClient class, which is created by calling GoogleAdsClientBuilder::build(). Both GoogleAdsClient and GoogleAdsClientBuilder are manually maintained 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/ (for example, V25), and the corresponding request and response message classes (such as MutateCampaignsRequest and SearchGoogleAdsRequest) are located in src/Google/Ads/GoogleAds/VX/Services/. Minor API releases (such as v25.1) are generated inside their major version directory (V25).

Usage

You must create a request object and pass it to the service client you want to use. Depending on whether parameters are required or optional, you have multiple ways of creating a request object, including a static build() factory method for passing required parameters.

Example 1.1: Methods with required parameters

The following sample code shows how to call CampaignServiceClient::mutateCampaigns(). Because both $customerId and $campaignOperations are required parameters, a static build() factory method that accepts both parameters is generated in the request class.

Pattern 1: Static build method (recommended)

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

Pattern 2: Fluent setters

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

Example 1.2: Methods with required and optional parameters

The following sample code calls GoogleAdsServiceClient::search(). In this example, the generated build() method 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 can set it explicitly using setReturnTotalResultsCount(). Alternatively, you can pass all parameters together in an associative array to the constructor of SearchGoogleAdsRequest, as shown in Pattern 3.

Pattern 1: Static build method with fluent setters

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

Pattern 2: Fluent setters

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

Pattern 3: Array constructor

$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 must construct the request object using setters or the array constructor.

Pattern 1: Fluent setters (recommended)

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

Pattern 2: Array constructor

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