googleads/google-ads-php

Google Ads API client for PHP

v3.2.0 2020-05-05 18:35 UTC

This package is auto-updated.

Last update: 2020-06-23 03:34:13 UTC


README

Minimum PHP Version Latest Stable Version Total Downloads License

Build Status codecov

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.
    • PHP: You can find the required minimum PHP version in "php" under the require key of composer.json. We usually set it to the minimum PHP version for which the PHP development team still provide security fixes. Whenever such a version is sunset, we'll update the composer file accordingly. Currently, the update frequency is around once a year based on the official schedule. Visit this page for introduction to PHP.
    • gRPC: To install the gRPC PHP extension, visit the Install the gRPC PHP extension section. It takes some time to install. To learn more about this requirement, please check the Transport guide.
      1. Install the extension using the command sudo pecl install grpc.
      2. Add a line extension=grpc.so to the php.ini file.
      3. Run php -i | grep grpc in a terminal: it is well installed and configured if it returns something
    • Protobuf: To install the Protobuf PHP extension, visit the C implementation section. It takes some time to install. If you encounter any error, you can skip this step and the PHP implementation will be used instead. More details can be found in the Protobuf implementations guide.
      1. Install the extension using the command sudo pecl install protobuf.
      2. Add a line extension=protobuf.so to the php.ini file.
      3. Run php -i | grep protobuf in a terminal: it is well installed and configured if it returns something
  • 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...

  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.

Transport

There are different types of transport that can be used. See the Transport guide for more information.

Protobuf

Protobuf is used regardless of the transport used to request the Google Ads API.

See the Protobuf guide for more information.

Running in a Docker container

See the Running in a Docker container guide.

Logging

See the Logging guide.

Proxy configuration

See the Proxy guide.

Performance

See the Performance guide.

Miscellaneous

Wiki

Issue tracker

API Documentation:

Support forum

Authors