Google Ads API client for PHP
This project hosts the PHP client library for the Google Ads API.
- Distributed via Composer and Packagist.
- Easy management of credentials.
- Easy creation of Google Ads API service clients.
- This library depends on Composer. If you don't
have it installed on your computer yet, follow the installation guide for
installation guide 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
- 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.
Clone this project in the directory of your choice via:
git clone https://github.com/googleads/google-ads-php.git
Change into the
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.
composer installat the command prompt. This will install all dependencies needed for using the library and running examples.
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.inifile you used for the AdWords API, copy and name it as
google_ads_php.ini. Simply change the section name from
If you're accessing the Google Ads API using your own credentials...
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.inifile in your home directory. Don't forget to fill in your developer token too.
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.
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
--helpas a command-line parameter.
To issue requests via the Google Ads API, you first need to create a
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();
$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();
Once you have an instance of
GoogleAdsClient, you can obtain a service client
for a particular service using one of the
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
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
docker exec -it $(docker ps -a -q) bash.
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|
|Debug message (e.g., call queries)||DEBUG||NOTICE|
You can configure some options for the default logger in the
[LOGGING] ; Optional logging settings. logFilePath = "path/to/your/file.log" logLevel = "INFO"
$googleAdsClient = (new GoogleAdsClientBuilder()) ... ->withLogger(new MyCustomLogger()) ->build();
If you need to connect to the Google Ads API through a proxy, you can do so by setting the
property in the
CONNECTION section of your
[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();