/googleads-php-lib

Google Ads API Client Library for PHP (AdWords and Ad Manager)

Primary LanguagePHPApache License 2.0Apache-2.0

Google Ads API PHP Client Library

This repository hosts the PHP client library for the Google Ad Manager SOAP API.

The AdWords API is sunset. You can use the new client library google-ads-php to access the new Google Ads API instead.

PHP version Build Status

Requirements and Preparation

  • System requirements and dependencies can be found in composer.json of this library. See this page for more details.
  • From version 60.0.0, this library requires the minimum PHP version to be 7.4. If you have an older version of PHP, composer command will download an older version of the googleads/googleads-php-lib library.
  • 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.

Getting started

Copy the sample Ad Manager adsapi_php.ini 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.

  1. Install the latest version using Composer.

    $ composer require googleads/googleads-php-lib

  2. Follow Getting started if you haven't done so.

  3. Follow Setting up your OAuth2 credentials if you haven't set up the credentials yet.

  4. 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.

  1. Run git clone https://github.com/googleads/googleads-php-lib.git at the command prompt.

  2. You'll get a googleads-php-lib directory. Navigate to it by running cd googleads-php-lib.

  3. Run composer install at the command prompt. This will install all dependencies needed for using the library and running examples.

  4. Follow Getting started if you haven't done so.

  5. Follow Setting up your OAuth2 credentials if you haven't set up the credentials yet.

  6. You can now use the library and run any examples you want. Try GetAllNetworks.php by executing the following command:

    $ php examples/AdManager/v202211/NetworkService/GetAllNetworks.php

Downloading a compressed tarball

This is suitable for those who only want to try out the Ad Manager API with this client library. The extracted directory of the tarball will contain only the examples/ directory.

  1. 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, admanager-examples-vX.Y.Z.tar.gz.

  2. Extract your downloaded file to any location on your computer.

  3. Navigate to the extracted directory (for example, admanager-examples-vX.Y.Z).

  4. Run composer install at the command prompt. This will install all dependencies needed for using the library and running examples.

  5. Follow Getting started if you haven't done so.

  6. Follow Setting up your OAuth2 credentials if you haven't set up the credentials yet.

  7. You can now run any examples you want. Try GetAllNetworks.php by executing the following command:

    $ php examples/AdManager/v202211/NetworkService/GetAllNetworks.php

Setting up your OAuth2 credentials

The Ad Manager API uses OAuth2 as the authentication mechanism. Follow the appropriate guide below based on your use case:

Basic usage

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

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 GetAllNetworks.php example gives you an idea of how to use this library.

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

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

$adManagerServices = new ServiceFactory();

$networkService = $adManagerServices->createNetworkService($session);

$networks = $networkService->getAllNetworks();

// Do something with the $networks.

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

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 for 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 the Ad Manager session builder:

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

Utilities

We provide some utilities in this client library for helping you use features in the Ad Manager API more conveniently.

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://ads.google.com/apis/ads/publisher/v202211/ActivityService?wsdl' :
failed to load external entity
"https://ads.google.com/apis/ads/publisher/v202211/ActivityService?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. You can view the Ad Manager API site here.

General 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 Ad Manager API questions, bug reports, or feature requests, post to the Ad Manager API Forum.

Announcements and updates

For general Ad Manager API and client library updates and news, you can follow the Sunset Announcements mailing list and rely on the deprecation schedule.