googleads-php-lib: A PHP repository from mikeaag

Google Ads API PHP Client Library

This project hosts the PHP client library for the various SOAP-based Ads APIs (AdWords and Ad Manager) at Google.

Welcome to the new ads API PHP client library!

The ads API PHP client library has been rewritten. If you're new to this library, read on! If you're already using our library, you may want to take a look at our Upgrading guide first.

Requirements and Preparation

System requirements and dependencies can be found in composer.json of this library. See this page for more details.
This library depends on Composer. If you don't have it installed on your computer yet, follow the installation guide for Linux/Unix/OS X or installation guide for Windows. For the rest of this guide, we're assuming that you're using Linux/Unix/OS X and have Composer installed 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, as well as a developer token. Make sure you've written down these credentials in advance.

Getting started

Copy the sample adsapi_php.ini for your product to your home directory and fill out the required properties before downloading the library. This library determines the home directory of your computer by using EnvironmentalVariables::getHome().

Downloading this library

There are three ways of downloading this library as described below.

Method	Target Users
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`	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	Those who only want to run example files.

Note

If you don't have OAuth2 credentials prior to using installed application flow, you'll need 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 composer require

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.

Install the latest version using Composer.

$ composer require googleads/googleads-php-lib

Follow Getting started if you haven't done so.
Follow Setting up your OAuth2 credentials if you haven't set up the credentials yet.
You can now use the library.

Using git clone

This method is suitable for those who want to alter or contribute to this library (e.g., submitting pull requests) or wish to try our examples. All files in this repository will be downloaded.

Run git clone https://github.com/googleads/googleads-php-lib.git at the command prompt.
You'll get a googleads-php-lib directory. Navigate to it by running cd googleads-php-lib.
Run composer install at the command prompt. This will install all dependencies needed for using the library and running examples.
Follow Getting started if you haven't done so.
Follow Setting up your OAuth2 credentials if you haven't set up the credentials yet.
You can now use the library and run any examples you want. Try GetCampaigns.php by executing the following command:
```
$ php examples/AdWords/v201806/BasicOperations/GetCampaigns.php
```

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.

On the releases page, 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.
Extract your downloaded file to any location on your computer.
Navigate to the extracted directory (for example, adwords-examples-vX.Y.Z).
Run composer install at the command prompt. This will install all dependencies needed for using the library and running examples.
Follow Getting started if you haven't done so.
Follow Setting up your OAuth2 credentials if you haven't set up the credentials yet.
You can now run any examples you want. Try GetCampaigns.php by executing the following command:
```
$ php examples/AdWords/v201806/BasicOperations/GetCampaigns.php
```

Setting up your OAuth2 credentials

The AdWords and Ad Manager APIs use OAuth2 as the authentication mechanism. Follow the appropriate guide below based on your use case.

If you're accessing an API using your own credentials...

If you're accessing an API on behalf of clients...

Using AdWords or Ad Manager

Basic usage

The best way to learn how to use this library is to review the examples for your product.

All our examples are meant to be run via the command line and not through a webpage.

If you're using 32-bit PHP, you'll need to change all instances of intval() to floatval() before running an example. This is due to some IDs exceeding the 32-bit PHP_INT_MAX that intval() changes your value to. In addition, when writing your own code, do not apply intval() on any attributes that are explicitly an integer.

The following snippet of code from the BasicOperations/GetCampaigns.php example for AdWords gives you an idea of how to use this library. The usage pattern is similar for Ad Manager.

use Google\AdsApi\AdWords\AdWordsServices;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\v201802\cm\CampaignService;
use Google\AdsApi\AdWords\v201802\cm\OrderBy;
use Google\AdsApi\AdWords\v201802\cm\Paging;
use Google\AdsApi\AdWords\v201802\cm\Selector;
use Google\AdsApi\Common\OAuth2TokenBuilder;

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

$session = (new AdWordsSessionBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

$adWordsServices = new AdWordsServices();

$campaignService = $adWordsServices->get($session, CampaignService::class);

// Create selector.
$selector = new Selector();
$selector->setFields(array('Id', 'Name'));
$selector->setOrdering(array(new OrderBy('Name', 'ASCENDING')));

// Create paging controls.
$selector->setPaging(new Paging(0, 100));

// Make the get request.
$page = $campaignService->get($selector);

// Do something with the $page.

The builder's fromFile() method looks for an adsapi_php.ini file in your home directory by default. If you want to store this file in another directory, pass the path of the file as an argument. For example:

fromFile('/config/myprops.ini')

It is highly recommended that you use an adsapi_php.ini file. However, if you don't want to or can't use one, you can use the OAuth2 token and ads session builders instead to set the same information. See the builders for details:

WSDL objects with names that are reserved PHP keywords

Class names

Note that some WSDL object types have names that are reserved PHP keywords and need to be augmented when used as PHP class names. The following is a list of these occurences.

Function => MatchingFunction
Parent => ParentCriterion

Constant names

Some WSDL enum values have names that are reserved PHP keywords and need to be modified when used as PHP constant names. For example, AND and DEFAULT are generated as AND_VALUE and DEFAULT_VALUE.

Logging

This library conforms to PSR-3 for logging and provides the following loggers:

AdWords

SOAP logger
Report downloader logger
Batch jobs utility logger

Ad Manager

SOAP logger
Report downloader logger

In general, each logger logs a summary and debug message for events (e.g., a SOAP API call). The level at which messages are logged depends on whether the event succeeded.

Log message \ Event status	Success	Failure
One-line summary	INFO	WARNING
Debug message (e.g., SOAP payload)	DEBUG	NOTICE

Configuring logging

By default, each of the library loggers logs to STDERR on a separate channel using a Monolog StreamHandler.

You can configure some options for these default loggers in the adsapi_php.ini file:

[LOGGING]
; Optional logging settings.
soapLogFilePath = "path/to/your/soap.log"
soapLogLevel = "NOTICE"

If you need to further customize logging, you can specify your own logger entirely by providing a logger that implements LoggerInterface in either the AdWords or Ad Manager session builders:

$session = (new AdWordsSessionBuilder())
    ...
    ->withSoapLogger(new MyCustomSoapLogger())
    ->withReportDownloaderLogger(new MyCustomReportDownloaderLogger())
    ->build();

Utilities

We provide some utilities in this client library for helping you use features in the AdWords and Ad Manager API more conveniently. Check out the following wikis for details:

Reporting

When downloading reports, you can set additional stream context options using the stream_context key to suit your needs (e.g., increasing the timeout as shown below). See also Guzzle FAQ for details.

$options = [
    'stream_context' => [
        'http' => ['timeout' => 120]
    ]
];
$requestOptionsFactory = new RequestOptionsFactory($session, $options);
$reportDownloader = new ReportDownloader($session, $requestOptionsFactory);

SSL CA files

PHP >= v5.6 automatically sets verify_peer to true and will do its best to find the most appropriate CA bundle on your system by default. 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().

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:

Fatal error: Uncaught SoapFault exception: [WSDL] SOAP-ERROR: Parsing WSDL:
Couldn't load from
'https://adwords.google.com/api/adwords/cm/v201806/CampaignService?wsdl' :
failed to load external entity
"https://adwords.google.com/api/adwords/cm/v201806/CampaignService?wsdl

To remedy, see Steps for troubleshooting CA file issues.

Documentation

PHPDoc for this library can be found in the gh-pages branch of this repository and can be viewed at:

General AdWords and Ad Manager API documentation can be found on our Google Developers site:

Coding Style

We use PSR-2 as a coding style standard. Assuming that you're at the root directory of your project, to check for coding style violations, run

vendor/bin/phpcs src --standard=phpcs_ruleset.xml -np

To automatically fix (fixable) coding style violations, run

vendor/bin/phpcbf src --standard=phpcs_ruleset.xml

Getting support

For client library specific bug reports, feature requests, and patches, create an issue on the issue tracker.

For general AdWords and Ad Manager API questions, bug reports, or feature requests, post to our forums:

Announcements and updates

For general ads API and client library updates and news, follow:

API deprecation schedules can be found at:

mikeaag/googleads-php-lib