Google Ads API Client Library for PHP
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Updated query to include the segments. prefix where required Feb 4, 2019
metadata/Google/Ads/GoogleAds/V0 Changes for release v0_7. Feb 1, 2019
src/Google/Ads/GoogleAds Added support for login-customer-id in GoogleAdsGapicClientTrait Feb 18, 2019
tests/Google/Ads/GoogleAds Updated getopt dependency to the latest version and fixed a test that… Feb 9, 2019
.gitattributes Initial commit for v0_1. Jun 6, 2018
.gitignore
CHANGELOG.md
CONTRIBUTING.md Initial commit for v0_1. Jun 6, 2018
LICENSE Initial commit for v0_1. Jun 6, 2018
README.md Update README to contain gRPC info Dec 20, 2018
composer.json Update google/gax to 0.38.0 (#27) Feb 15, 2019
phpcs_ruleset.xml Initial commit for v0_1. Jun 6, 2018
phpunit.xml.dist Initial commit for v0_1. Jun 6, 2018

README.md

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

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.

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

Issue tracker

API Documentation:

Support forum

Authors