Release 32.1.0.

Author: fiboknacky

CHANGELOG.md

@@ -1,3 +1,32 @@
+### 32.1.0
+
+##### DFP
+
+*   Added examples for v201711:
+    *   InventoryService\GetAdUnitHierarchy
+    *   InventoryService\GetTopLevelAdUnits
+    *   LineItemService\CreateLineItemsWithCustomCriteria
+    *   NetworkService\GetCurrentNetwork
+    *   NetworkService\MakeTestNetwork
+    *   PublisherQueryLanguageService\GetAllLineItems
+    *   PublisherQueryLanguageService\GetAllProgrammaticBuyers
+    *   PublisherQueryLanguageService\GetGeoTargets
+    *   ReportService\RunReachReport
+    *   ReportService\RunReportWithCustomFields
+    *   TeamService\UpdateTeams
+    *   UserService\GetCurrentUser
+    *   UserService\UpdateUsers
+
+*   Added utility class `CsvFiles` for v201711.
+
+##### Common
+
+*   Fixed
+    [issue #399](https://github.com/googleads/googleads-php-lib/issues/399).
+*   Fixed the issue that a wrong path to local WSDL files was specified in
+    `AdsSoapClient`.
+*   Accepted [PR #401](https://github.com/googleads/googleads-php-lib/pull/401).
+
 ### 32.0.0
 
 ##### AdWords

README.md

@@ -13,89 +13,140 @@ This project hosts the PHP client library for the various SOAP-based Ads APIs
 
 [![PHP version](https://badge.fury.io/ph/googleads%2Fgoogleads-php-lib.svg)](https://badge.fury.io/ph/googleads%2Fgoogleads-php-lib) [![Build Status](https://travis-ci.org/googleads/googleads-php-lib.svg?branch=master)](https://travis-ci.org/googleads/googleads-php-lib)
 
-### Getting started
-
-1.  Install the latest version using [Composer](https://getcomposer.org/).
+### Requirements and Preparation
+
+*   System requirements and dependencies can be found in `composer.json` of this
+    library. See [this page](https://getcomposer.org/doc/01-basic-usage.md) for
+    more details.
+*   This library depends on [Composer](https://getcomposer.org/). If you don't
+    have it installed on your computer yet, follow the
+    [installation guide for Linux/Unix/OS X](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx)
+    or [installation guide for Windows](https://getcomposer.org/doc/00-intro.md#installation-windows).
+    For the rest of this guide, we're assuming that you're using
+    Linux/Unix/OS X and have Composer installed [globally](https://getcomposer.org/doc/00-intro.md#globally),
+    thus, your installed Composer is available on the command line as `composer`.
+*   To use this library to connect to AdWords API, you need an
+    [OAuth 2 client ID and secret](https://developers.google.com/adwords/api/docs/guides/first-api-call#oauth2_client_id_and_client_secret),
+    as well as a [developer token](https://developers.google.com/adwords/api/docs/guides/first-api-call#developer_token).
+    Make sure you've written down these credentials in advance.
 
-    ```
-    $ php composer.phar require googleads/googleads-php-lib
-    ```
+### Getting started
 
-1.  Copy the sample `adsapi_php.ini` for your product to your home directory and
-    fill out the required properties.
+Copy the sample `adsapi_php.ini` for your product to your
+[home directory](https://en.wikipedia.org/wiki/Home_directory#Default_home_directory_per_operating_system)
+and fill out the required properties before downloading the library.
+This library determines the home directory of your computer by using
+[`EnvironmentalVariables::getHome()`](https://github.com/googleads/googleads-php-lib/blob/master/src/Google/AdsApi/Common/Util/EnvironmentalVariables.php#L34).
 
     *   [AdWords
         adsapi_php.ini](https://github.com/googleads/googleads-php-lib/blob/master/examples/AdWords/adsapi_php.ini)
     *   [DFP
         adsapi_php.ini](https://github.com/googleads/googleads-php-lib/blob/master/examples/Dfp/adsapi_php.ini)
 
-1.  Set up your OAuth2 credentials.
+### Downloading this library
 
-    The AdWords and DoubleClick for Publishers APIs use
-    [OAuth2](https://oauth.net/2/) as the authentication mechanism. Follow the
-    appropriate guide below based on your use case.
+There are three ways of downloading this library as described below.
 
-    **If you're accessing an API using your own credentials...**
+| Method                                                                | Target Users                                                                                                                  |
+|-----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
+| [Using `composer require`](#using-composer-require)                   | Those who want to **use this library as a third-party library** for their projects and thus example files are not needed.     |
+| [Using `git clone`](#using-git-clone)                                 | Those who want to **alter or contribute to this library** (e.g., submitting a pull request) or want to **run example files**. |
+| [Downloading a compressed tarball](#downloading-a-compressed-tarball) | Those who only want to **run example files**.                                                                                 |
 
-    *   [Using
-        AdWords](https://github.com/googleads/googleads-php-lib/wiki/API-access-using-own-credentials-\(installed-application-flow\))
-    *   [Using
-        DFP](https://github.com/googleads/googleads-php-lib/wiki/API-access-using-own-credentials-\(server-to-server-flow\))
+#### Note
 
-    **If you're accessing an API on behalf of clients...**
+*   If you don't have OAuth2 credentials prior to using
+    [installed application flow](https://github.com/googleads/googleads-php-lib/wiki/API-access-using-own-credentials-(installed-application-flow)),
+    you'll need [examples/Auth/GetRefreshToken.php](https://github.com/googleads/googleads-php-lib/blob/master/examples/Auth/GetRefreshToken.php).
+    In this case, using `composer require` is not an option since there are no
+    example files downloaded with the library.
+*   **Our examples are meant to be run from the command line and not as a
+    webpage.** If you run them as a webpage, results may not be shown
+    properly.
 
-    *   [Using AdWords or
-        DFP](https://github.com/googleads/googleads-php-lib/wiki/API-access-on-behalf-of-your-clients-\(web-flow\))
+### Using composer require
 
-### Running examples
+The steps below download this library as a third-party library for your projects.
+The library will be downloaded by Composer and stored under the `vendor/` directory.
+**Examples are NOT downloaded by this download method.**
+
+1.  Install the latest version using [Composer](https://getcomposer.org/).
+
+    ```
+    $ composer require googleads/googleads-php-lib
+    ```
 
-You have two ways of getting example files: using `git clone` or downloading a
-compressed tarball.
+1.  Follow [Getting started](#getting-started) if you haven't done so.
+1.  Follow [Setting up your OAuth2 credentials](#setting-up-your-oauth2-credentials)
+    if you haven't set up the credentials yet.
+1.  You can now use the library.
 
-#### Using git clone
+### Using git clone
 
 This method is suitable for those who want to alter or contribute to
-this library. All files in this repository will be downloaded.
+this library (e.g., submitting pull requests) or wish to try our examples.
+**All** files in this repository will be downloaded.
 
-1.  Run `git clone https://github.com/googleads/googleads-php-lib.git` in
-    your command prompt.
-1.  You will get a **googleads-php-lib** directory. Navigate to it by running
+1.  Run `git clone https://github.com/googleads/googleads-php-lib.git` at
+    the command prompt.
+1.  You'll get a **googleads-php-lib** directory. Navigate to it by running
     `cd googleads-php-lib`.
-1.  Run `php composer.phar install`. This will install all dependencies needed
-    for running examples.
-1.  Set up your `adsapi_php.ini` file if you've not done so. See steps 2 and 3
-    in [Getting Started](#getting-started) for detail.
-1.  You can now run any examples you want. Try
-    [GetCampaigns.php](https://github.com/googleads/googleads-php-lib/blob/master/examples/AdWords/v201705/BasicOperations/GetCampaigns.php)
+1.  Run `composer install` at the command prompt. This will install all
+    dependencies needed for using the library and running examples.
+1.  Follow [Getting started](#getting-started) if you haven't done so.
+1.  Follow [Setting up your OAuth2 credentials](#setting-up-your-oauth2-credentials)
+    if you haven't set up the credentials yet.
+1.  You can now use the library and run any examples you want. Try
+    [GetCampaigns.php](https://github.com/googleads/googleads-php-lib/blob/master/examples/AdWords/v201710/BasicOperations/GetCampaigns.php)
     by executing the following command:
 
     ```
-    $ php examples/AdWords/v201705/BasicOperations/GetCampaigns.php
+    $ php examples/AdWords/v201710/BasicOperations/GetCampaigns.php
     ```
 
-#### Downloading a compressed tarball
+### Downloading a compressed tarball
 
 This is suitable for those who only want to try out the AdWords API with this
 client library. The extracted directory of the tarball will contain only the
 `examples/` directory.
 
-1.  In the [releases](https://github.com/googleads/googleads-php-lib/releases)
-    page, select a version you want to try. Then, under **Download**, you can
-    see the names of compressed tarballs for AdWords and DFP. Click on the name
-    of compressed tarball you want to try, e.g.,
-    **adwords-examples-vX.Y.Z.tar.gz** for AdWords.
-1.  Extract your downloaded file to any location in your computer.
-1.  Change to the extracted directory (such as **adwords-examples-vX.Y.Z**).
-1.  Follow all the steps in the `README.md` file in the directory, including
-    running `php composer.phar install` and setting up `adsapi_php.ini`.
+1.  On the [releases page](https://github.com/googleads/googleads-php-lib/releases),
+    select a version you want to try. Then, under **Download**, select the tarball
+    of your choice. The name of the tarball indicates which product it belongs to,
+    for example, **adwords-examples-vX.Y.Z.tar.gz**.
+1.  Extract your downloaded file to any location on your computer.
+1.  Navigate to the extracted directory (for example, **adwords-examples-vX.Y.Z**).
+1.  Run `composer install` at the command prompt. This will install all dependencies
+    needed for using the library and running examples.
+1.  Follow [Getting started](#getting-started) if you haven't done so.
+1.  Follow [Setting up your OAuth2 credentials](#setting-up-your-oauth2-credentials)
+    if you haven't set up the credentials yet.
 1.  You can now run any examples you want. Try
-    [GetCampaigns.php](https://github.com/googleads/googleads-php-lib/blob/master/examples/AdWords/v201705/BasicOperations/GetCampaigns.php)
+    [GetCampaigns.php](https://github.com/googleads/googleads-php-lib/blob/master/examples/AdWords/v201710/BasicOperations/GetCampaigns.php)
     by executing the following command:
 
     ```
-    $ php examples/AdWords/v201705/BasicOperations/GetCampaigns.php
+    $ php examples/AdWords/v201710/BasicOperations/GetCampaigns.php
     ```
 
+### Setting up your OAuth2 credentials
+
+The AdWords and DoubleClick for Publishers APIs use
+[OAuth2](https://oauth.net/2/) as the authentication mechanism. Follow the
+appropriate guide below based on your use case.
+
+**If you're accessing an API using your own credentials...**
+
+*   [Using
+    AdWords](https://github.com/googleads/googleads-php-lib/wiki/API-access-using-own-credentials-\(installed-application-flow\))
+*   [Using
+    DFP](https://github.com/googleads/googleads-php-lib/wiki/API-access-using-own-credentials-\(server-to-server-flow\))
+
+**If you're accessing an API on behalf of clients...**
+
+*   [Using AdWords or
+    DFP](https://github.com/googleads/googleads-php-lib/wiki/API-access-on-behalf-of-your-clients-\(web-flow\))
+
 ### Basic usage
 
 The best way to learn how to use this library is to review the examples for your
@@ -273,16 +324,25 @@ However, not all systems have a known CA bundle on disk (e.g. Windows). This
 library tries to locate CA bundles on your system by using Guzzle
 [`default_ca_bundle()`](https://github.com/guzzle/guzzle/blob/6.0.2/src/functions.php#L157).
 
-If this library can't find CA bundle on your system, you will get this error
-message:
+If this library can't find a CA bundle on your system, you'll get an error
+message similar to this:
+
+```
+cURL error 60: SSL certificate problem: unable to get local issuer certificate.
+```
+
+CA file issues can also cause an error like this:
 
 ```
-cURL error 60: SSL certificate problem: unable to get local issuer certificate".
+Fatal error: Uncaught SoapFault exception: [WSDL] SOAP-ERROR: Parsing WSDL:
+Couldn't load from
+'https://adwords.google.com/api/adwords/cm/v201710/CampaignService?wsdl' :
+failed to load external entity
+"https://adwords.google.com/api/adwords/cm/v201710/CampaignService?wsdl
 ```
 
-To resolve this, manually specify your SSL CA file location with
-SoapSettinsBuilder's
-[`withSslCaFile()`](https://github.com/googleads/googleads-php-lib/blob/27.1.0/src/Google/AdsApi/Common/SoapSettingsBuilder.php#L182).
+To remedy, see [Steps for troubleshooting CA file issues
+](https://github.com/googleads/googleads-php-lib/wiki/Steps-for-troubleshooting-CA-file-issues).
 
 ### Documentation
 

examples/AdWords/v201702/AccountManagement/GetAccountChanges.php

@@ -52,6 +52,7 @@ public static function runExample(AdWordsServices $adWordsServices,
 
     // Get an array of all campaign IDs.
     $campaignIds = [];
+    $totalNumEntries = 0;
     do {
       $page = $campaignService->get($selector);
 

examples/AdWords/v201702/AccountManagement/GetAccountHierarchy.php

@@ -25,6 +25,7 @@
 use Google\AdsApi\AdWords\v201702\cm\Paging;
 use Google\AdsApi\AdWords\v201702\cm\Selector;
 use Google\AdsApi\AdWords\v201702\cm\SortOrder;
+use Google\AdsApi\AdWords\v201702\mcm\ManagedCustomer;
 use Google\AdsApi\AdWords\v201702\mcm\ManagedCustomerService;
 use Google\AdsApi\Common\OAuth2TokenBuilder;
 

examples/AdWords/v201702/BasicOperations/AddKeywords.php

@@ -31,6 +31,7 @@
 use Google\AdsApi\AdWords\v201702\cm\Money;
 use Google\AdsApi\AdWords\v201702\cm\NegativeAdGroupCriterion;
 use Google\AdsApi\AdWords\v201702\cm\Operator;
+use Google\AdsApi\AdWords\v201702\cm\UrlList;
 use Google\AdsApi\AdWords\v201702\cm\UserStatus;
 use Google\AdsApi\Common\OAuth2TokenBuilder;
 
@@ -61,7 +62,8 @@ public static function runExample(AdWordsServices $adWordsServices,
 
     // Set additional settings (optional).
     $adGroupCriterion->setUserStatus(UserStatus::PAUSED);
-    $adGroupCriterion->setFinalUrls(['http://www.example.com/mars']);
+    $adGroupCriterion->setFinalUrls(
+        new UrlList(['http://www.example.com/mars']));
 
     // Set bids (optional).
     $bid = new CpcBid();

examples/AdWords/v201702/BasicOperations/UpdateKeyword.php

@@ -26,6 +26,7 @@
 use Google\AdsApi\AdWords\v201702\cm\BiddableAdGroupCriterion;
 use Google\AdsApi\AdWords\v201702\cm\Criterion;
 use Google\AdsApi\AdWords\v201702\cm\Operator;
+use Google\AdsApi\AdWords\v201702\cm\UrlList;
 use Google\AdsApi\Common\OAuth2TokenBuilder;
 
 /**
@@ -52,7 +53,8 @@ public static function runExample(AdWordsServices $adWordsServices,
     $adGroupCriterion->setCriterion(new Criterion($criterionId));
 
     // Update final URL.
-    $adGroupCriterion->setFinalUrls(['http://www.example.com/new']);
+    $adGroupCriterion->setFinalUrls(
+        new UrlList(['http://www.example.com/new']));
 
     // Create ad group criterion operation and add it to the list.
     $operation = new AdGroupCriterionOperation();

examples/AdWords/v201702/CampaignManagement/AddDraft.php

@@ -88,8 +88,7 @@ public static function runExample(AdWordsServices $adWordsServices,
     $operations[] = $operation;
 
     // Create a campaign criterion on the server.
-    $campaignCriterion =
-        $campaignCriterionService->mutate($operations)->getValue()[0];
+    $campaignCriterionService->mutate($operations);
 
     printf("Draft updated to include criteria in the campaign with ID %d.\n",
         $draft->getDraftCampaignId());

examples/AdWords/v201702/CampaignManagement/SetAdParameters.php

@@ -45,20 +45,20 @@ public static function runExample(AdWordsServices $adWordsServices,
     $adParam1 = new AdParam($adGroupId, $keywordId, '100', 1);
     $adParam2 = new AdParam($adGroupId, $keywordId, '$40', 2);
 
-    $adParamOperation1s = [];
+    $adParamOperations = [];
 
     $adParamOperation1 = new AdParamOperation();
     $adParamOperation1->setOperand($adParam1);
     $adParamOperation1->setOperator(Operator::SET);
-    $operations[] = $adParamOperation1;
+    $adParamOperations[] = $adParamOperation1;
 
     $adParamOperation2 = new AdParamOperation();
     $adParamOperation2->setOperand($adParam2);
     $adParamOperation2->setOperator(Operator::SET);
-    $operations[] = $adParamOperation2;
+    $adParamOperations[] = $adParamOperation2;
 
     // Add ad params on the server.
-    $adParams = $adParamService->mutate($operations);
+    $adParams = $adParamService->mutate($adParamOperations);
 
     // Print out some information about added ad parameters.
     foreach ($adParams as $adParam) {

examples/AdWords/v201702/CampaignManagement/ValidateTextAd.php

@@ -64,7 +64,7 @@ public static function runExample(AdWordsServices $adWordsServices,
     $operations[] = $operation;
 
     try {
-      $result = $adGroupAdService->mutate($operations);
+      $adGroupAdService->mutate($operations);
       printf("The expanded text ad is valid.\n");
     } catch (ApiException $e) {
       $errors = $e->getErrors();

examples/AdWords/v201702/ErrorHandling/HandlePartialFailures.php

@@ -21,7 +21,6 @@
 use Google\AdsApi\AdWords\AdWordsServices;
 use Google\AdsApi\AdWords\AdWordsSession;
 use Google\AdsApi\AdWords\AdWordsSessionBuilder;
-use Google\AdsApi\AdWords\v201702\cm\AdGroupCriterion;
 use Google\AdsApi\AdWords\v201702\cm\AdGroupCriterionOperation;
 use Google\AdsApi\AdWords\v201702\cm\AdGroupCriterionService;
 use Google\AdsApi\AdWords\v201702\cm\BiddableAdGroupCriterion;