googleads/google-ads-php

Google Ads API client for PHP

v1.4.0 2019-06-12 17:40 UTC

README

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

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

  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();

Proxy configuration

If you need to connect to the Google Ads API through a proxy, you can do so by setting the proxy property in the CONNECTION section of your google_ads_php.ini file:

[CONNECTION]
; Optional proxy settings to be used by requests.
; If you don't have username and password, just specify host and port.
proxy = "protocol://user:pass@host:port"

Alternatively, you can configure the proxy setting programmatically like every other configuration setting:

$googleAdsClient = (new GoogleAdsClientBuilder())
    ...
    ->withProxy('protocol://user:pass@host:port')
    ->build();

Miscellaneous

Wiki

Issue tracker

API Documentation:

Support forum

Authors