Google Ads API Client Library for PHP

This project hosts the PHP client library for the Google Ads API.

Features

• Distributed via Composer and Packagist.
• Easy management of credentials.
• Easy creation of Google Ads API service clients.

Requirements

• 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.
• System requirements and dependencies can be found in composer.json of this library.
  • To install the gRPC PHP extension, see this page.
• You need a developer token to connect to the Google Ads API.

Getting started

1. Clone this project in the directory of your choice via:

   git clone https://github.com/googleads/google-ads-php.git
   

2. Change into the google-ads-php directory.

   cd google-ads-php
   

   You'll see some files and subdirectories:

   • composer.json: the composer file, which holds the requirements of this library.
   • src: source code of the library.
   • tests: tests of the library code.
   • examples: many examples that demonstrate how to use the library to execute common use cases via the Google Ads API.
   • metadata: some metadata files used internally by the source code. They're automatically generated files, so you shouldn't modify them.

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

4. Set up your OAuth2 credentials.

   The Google Ads API uses OAuth2 as the authentication mechanism. Choose the appropriate option below based on your use case, and read and follow the instructions that the example prints to the console.

   If you already have credentials for the AdWords API...

   • If you have the adsapi_php.ini file you used for the AdWords API, copy and name it as google_ads_php.ini. Simply change the section name from [ADWORDS] to [GOOGLE_ADS].

   • If you don't have the file, copy the sample google_ads_php.ini to your home directory. This library determines the home directory of your computer by using EnvironmentalVariables::getHome().

   If you're accessing the Google Ads API using your own credentials...

   • Copy the sample google_ads_php.ini to your home directory. This library determines the home directory of your computer by using EnvironmentalVariables::getHome().

   • Follow the instructions at https://developers.google.com/google-ads/api/docs/oauth/cloud-project to create an OAuth2 client ID and secret for the installed application OAuth2 flow.

   • Run the AuthenticateInStandaloneApplication example, which will prompt you for your OAuth2 client ID and secret.

   • Copy the output from the last step of the example into the google_ads_php.ini file in your home directory. Don't forget to fill in your developer token too.

5. Run the GetCampaigns example to test if your credentials are valid. You also need to pass your Google Ads account's customer ID without dashes as a command-line parameter:

   php examples/BasicOperations/GetCampaigns.php --customerId <YOUR_CUSTOMER_ID>
   

   NOTE: Code examples are meant to be run from command prompt, not via the web browsers.

6. Explore other examples.

   The examples directory contains several useful examples. Most of the examples require parameters. You can see what are required by running code examples with --help as a command-line parameter.

Basic usage

To issue requests via the Google Ads API, you first need to create a GoogleAdsClient. For convenience, you can store the required settings in a properties file (google_ads_php.ini) with the following format:

[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

If you're authenticating as a manager account, additionally you must specify the manager account ID (with hyphens removed) as the login customer ID:

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

This configuration file format is similar to the format used in the AdWords API's client library for PHP.

If you have a google_ads_php.ini configuration file in the above format in your home directory, you can use the no-arg version of fromFile() as follows:

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

where $oAuth2Credential was created by:

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

If your configuration file is not in your home directory, you can pass the file location to the fromFile methods as follows:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();
$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

You can also construct an OAuth2 credential object by specifying the client ID, client secret, and refresh token at runtime, then pass that to the GoogleAdsClientBuilder as follows:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID')
    ->withClientSecret('INSERT_CLIENT_SECRET')
    ->withRefreshToken('INSERT_REFRESH_TOKEN')
    ->build();
$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withDeveloperToken('INSERT_DEVELOPER_TOKEN_HERE')
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

Get a service client

Once you have an instance of GoogleAdsClient, you can obtain a service client for a particular service using one of the get...ServiceClient() methods.

Running in a Docker container

You can also execute the examples and develop your Google Ads API application inside a Docker container, built using the provided Dockerfile.

To do so, provided that you have a Docker environment installed, you can run the following command in the directory where you cloned this repository:

docker-compose up --build -d

This will provide a Docker container instance with all the required dependencies already installed.

To open a BASH shell inside the Docker container, you can run docker ps to get the container id and then run docker exec -it <YOUR_CONTAINER_ID> bash; this will allow you to run code examples and other applications inside the container.

As a shorthand, in case you only have a single Docker container running on your machine, you can also run docker exec -it $(docker ps -a -q) bash.

Logging

This library conforms to PSR-3 for logging and provides a logger for gRPC calls.

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., call queries)	DEBUG	NOTICE

Configuring logging

By default, each of the library loggers logs to STDERR on a channel with default name specified here using a Monolog StreamHandler.

You can configure some options for the default logger in the google_ads_php.ini file:

[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "INFO"

If you need to further customize logging, you can specify your own logger entirely by providing a logger that implements LoggerInterface in GoogleAdsClientBuilder:

$googleAdsClient = (new GoogleAdsClientBuilder())
    ...
    ->withLogger(new MyCustomLogger())
    ->build();

Miscellaneous

Wiki

• https://github.com/googleads/google-ads-php/wiki

Issue tracker

• https://github.com/googleads/google-ads-php/issues

API Documentation:

• https://developers.google.com/google-ads/api/docs

Support forum

• https://groups.google.com/forum/#!forum/adwords-api

Authors

• Thanet Knack Praneenararat
• Mattia Tommasone