The source code in the `src/Google/Ads/GoogleAds/VX`
directory of the Google Ads API PHP client library, where <var translate="no">X</var> is the Google Ads API
version number, is automatically generated using [the GAPIC (Generated API
Client) Generator](https://github.com/googleapis/gapic-generator), based on the [published proto
files](https://github.com/googleapis/googleapis/tree/master/google/ads/googleads).

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, `V26`), 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 `v26.1`) are generated inside their major
version directory (`V26`).

## 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)

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

#### Pattern 2: Fluent setters

```php
$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

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

#### Pattern 2: Fluent setters

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

#### Pattern 3: Array constructor

```php
$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)

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

#### Pattern 2: Array constructor

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