Skip to content

Commit 47636e5

Browse files
vtsaovtsao
committed
Update README.md
1 parent 681cec8 commit 47636e5

File tree

1 file changed

+133
-141
lines changed

1 file changed

+133
-141
lines changed

‎README.md‎

Lines changed: 133 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -1,154 +1,133 @@
1-
## The Google Ads APIs PHP Client Library
1+
## Google Ads API PHP Client Library
22

33
This project hosts the PHP client library for the various SOAP-based Ads APIs
44
(AdWords and DFP) at Google.
55

6+
### Requirements
67

7-
### Features
8+
PHP
89

9-
* Provides easy SOAP logging of API calls.
10-
* Automatic handling of SOAP headers.
11-
* Easy management of credentials, authentication, and session information.
12-
* Examples to that show how to access API services.
13-
* PHPDoc - [AdWords](http://googleads.github.io/googleads-php-lib/AdWords/),
14-
[DFP](http://googleads.github.io/googleads-php-lib/Dfp/)
10+
* [PHP 5.3 and higher](http://php.net/supported-versions.php)
11+
* Required PHP extensions:
12+
* [SoapClient](http://us3.php.net/manual/en/book.soap.php) (`--enable-soap`)
13+
* [OpenSSL](http://php.net/manual/en/book.openssl.php) (`--with-ssl`)
14+
* [cURL](http://php.net/manual/en/book.curl.php) (`--with-curl`)
1515

16+
Testing
1617

17-
### Requirements
18+
* [PHPUnit](http://www.phpunit.de)
1819

19-
PHP
20-
- [PHP 5.3 and higher](http://php.net/supported-versions.php)
21-
- Required PHP extensions:
22-
- [SoapClient](http://us3.php.net/manual/en/book.soap.php) (--enable-soap)
23-
- [OpenSSL](http://php.net/manual/en/book.openssl.php) (--with-ssl)
24-
- [cURL](http://php.net/manual/en/book.curl.php) (--with-curl)
25-
26-
Build environment
27-
- [PHPUnit](http://www.phpunit.de)
28-
- [Phing](http://phing.info)
29-
- Modified wsdl2php-interpreter (included in this project)
30-
- Original: http://code.google.com/p/wsdl2php-interpreter
31-
- Required PHP extensions:
32-
- [XSLTProcessor](http://php.net/manual/en/class.xsltprocessor.php)
33-
(--with-xsl)
20+
### Getting started
3421

22+
1. Download and install the client library.
3523

36-
### Announcements and updates
24+
Download the latest examples and lib tarball distribution from the
25+
[releases section](https://github.com/googleads/googleads-php-lib/releases). To
26+
install the client library, either copy the contents of the `lib/` folder into a
27+
location on your PHP include path, or add the current directory path of the
28+
`lib/` folder to your PHP include path.
3729

38-
For API and client library updates and news, please follow our [Google+ Ads
39-
Developers page](https://plus.google.com/+GoogleAdsDevelopers/posts) and our
40-
[Google Ads Developers blog](http://googleadsdeveloper.blogspot.com).
30+
1. **[Alternative]** install via Composer.
4131

32+
You may also install this library via [Composer](https://getcomposer.org).
4233

43-
### Support forum
34+
```
35+
$ php composer.phar require googleads/googleads-php-lib
36+
```
4437

45-
If you have questions about the client library or the APIs, you can ask them on our forums:
46-
* [AdWords API Forum](https://groups.google.com/group/adwords-api)
47-
* [DoubleClick for Publishers API Forum](https://groups.google.com/forum/#!forum/google-doubleclick-for-publishers-api)
38+
> **Caveats with using Composer**
4839
49-
### Getting started
40+
> Because this library isn't namespaced (see #4), there are some class naming
41+
> conflicts with versioned utilities. E.g., [src/Google/Api/Ads/AdWords/Util]
42+
> (https://github.com/googleads/googleads-php-lib/tree/master/src/Google/Api/Ads/AdWords/Util).
43+
> Thus, these versioned utility src paths aren't included in the `classmap` of
44+
> [composer.json](https://github.com/googleads/googleads-php-lib/blob/master/composer.json).
45+
> So if you use composer, you will need to manually specify the version of the
46+
> utility files you're using. E.g., if you're using AdWords v201603, then in
47+
> your project's `composer.json` file, you can add those utility files to your
48+
> `classmap`:
5049
51-
1\. Register an OAuth 2 application.
50+
> ```json
51+
> "classmap": [
52+
> "vendor/googleads/googleads-php-lib/src/Google/Api/Ads/AdWords/Util/v201603"
53+
> ]
54+
> ```
5255
53-
You will need to register an OAuth2 application to get a valid client ID and
54-
secret. See the [Using OAuth 2 wiki page]
55-
(https://github.com/googleads/googleads-php-lib/wiki/Using-OAuth-2.0) for more information.
56+
1. Copy the sample **auth.ini** and **settings.ini** for your product to your
57+
home directory and fill out the required properties.
5658
57-
2\. Download the client library.
59+
* AdWords - [auth.ini](https://github.com/googleads/googleads-php-lib/blob/master/src/Google/Api/Ads/AdWords/auth.ini),
60+
[settings.ini](https://github.com/googleads/googleads-php-lib/blob/master/src/Google/Api/Ads/AdWords/settings.ini)
61+
* DFP - [auth.ini](https://github.com/googleads/googleads-php-lib/blob/master/src/Google/Api/Ads/Dfp/auth.ini),
62+
[settings.ini](https://github.com/googleads/googleads-php-lib/blob/master/src/Google/Api/Ads/Dfp/settings.ini)
5863
59-
The client library source can be found with the example distributions in the
60-
[releases section](https://github.com/googleads/googleads-php-lib/releases) of
61-
this GitHub project. Download the examples for the product you are working with
62-
and untar it.
64+
1. Setup your OAuth2 credentials.
6365
64-
3\. Enter your OAuth 2 and account credentials.
66+
The AdWords and DoubleClick for Publishers APIs use
67+
[OAuth2](http://oauth.net/2/) as the authentication mechanism. Follow the
68+
appropriate guide below based on your use case.
6569
66-
In the distribution you will find a lib folder. Under
67-
lib/Google/Api/Ads/[PRODUCT]/ you will find an auth.ini file. Open the auth.ini
68-
file and enter your OAuth 2 client ID and secret that you generated in step 1.
69-
Also enter the required product specific credentials, such as network code for
70-
DFP and developer token for AdWords.
70+
**If you're accessing an API using your own credentials...**
7171
72-
> It is recommended that during development of your library, you use a test
73-
> network/account. For DFP, you can follow instructions for how to obtain a
74-
> test network here:
75-
> https://developers.google.com/doubleclick-publishers/docs/start
76-
> For AdWords, you can follow instructions here:
77-
> https://developers.google.com/adwords/api/docs/test-accounts
72+
* [Using AdWords](https://github.com/googleads/googleads-php-lib/wiki/API-access-using-own-credentials-(installed-application-flow))
73+
* [Using DFP](https://github.com/googleads/googleads-php-lib/wiki/API-access-using-own-credentials-(installed-application-flow))
7874
79-
Now in your distribution, navigate to examples/[PRODUCT]/Auth and run the
80-
GetRefreshToken.php example. Copy the refresh token the example produces into
81-
the auth.ini file mentioned above.
75+
### Basic usage
8276
83-
4\. Run an example.
77+
The best way to learn how to use this library is to review the examples for your
78+
product.
8479
85-
To ensure you have setup credentials properly, run the GetAllCompanies.php
86-
example located in examples/Dfp/v201311/CompanyService/ if you're using DFP.
80+
* [AdWords examples](https://github.com/googleads/googleads-php-lib/tree/master/examples/AdWords)
81+
* [DFP examples](https://github.com/googleads/googleads-php-lib/tree/master/examples/Dfp)
8782
88-
If you're using AdWords, run the GetCampaigns.php example located in
89-
examples/AdWords/v201309/BasicOperations/.
83+
> All our examples are meant to be run via the command line and not as a
84+
> webpage.
9085
91-
5\. Install the client library.
86+
The following snippet of code from the **BasicOperations/GetCampaigns.php**
87+
example for AdWords gives you an idea of how to use this library. The usage
88+
pattern is similar for DFP.
9289
93-
To install the client library, either copy the lib/ folder into where you store
94-
your PHP source files that is on your PHP include path, or add the current
95-
directory path of the lib/ folder to your PHP include path.
90+
```php
91+
require_once 'Google/Api/Ads/AdWords/Lib/AdWordsUser.php';
9692
93+
$user = new AdWordsUser();
9794
98-
### Basic usage
95+
$campaignService = $user->GetService('CampaignService', 'v201603');
9996
100-
The following example is for AdWords, but the general code applies to all
101-
products.
97+
// Create selector.
98+
$selector = new Selector();
99+
$selector->fields = array('Id', 'Name');
100+
$selector->ordering[] = new OrderBy('Name', 'ASCENDING');
102101
102+
// Create paging controls.
103+
$selector->paging = new Paging(0, AdWordsConstants::RECOMMENDED_PAGE_SIZE);
103104
104-
```php
105+
// Make the get request.
106+
$page = $campaignService->get($selector);
105107
106-
// Set the include path and the require the folowing PHP file.
107-
//
108-
// You can set the include path to src directory or reference
109-
// AdWordsUser.php directly via require_once.
110-
// $path = '/path/to/pda_api_php_lib/src';
111-
$path = dirname(__FILE__) . '/../../../src';
112-
set_include_path(get_include_path() . PATH_SEPARATOR . $path);
113-
require_once 'Google/Api/Ads/AdWords/Lib/AdWordsUser.php';
108+
// Do something with the $page.
109+
```
114110
115-
// Create an AdWordsUser instance using the default constructor, which will load
116-
// information from the auth.ini file as described above.
117-
$user = new AdWordsUser();
111+
The `AdWordsUser` constructor method looks for an **auth.ini** file in your home
112+
directory by default. If you want to store this file in another directory, pass
113+
the path of the file as an argument. For example:
118114

119-
// Optionally, enable logging to capture the content of SOAP requests and
120-
// responses.
121-
$user->LogDefaults();
122-
123-
// Instantiate the desired service class by calling the get***Service method on
124-
// the AdWordsUser instance.
125-
$campaignService = $user->GetService('CampaignService', 'v201309');
126-
127-
// Create data objects and invoke methods on the service class instance. The
128-
// data objects and methods map directly to the data objects and requests for
129-
// the corresponding web service.
130-
131-
// Create new campaign structure.
132-
$campaign = new Campaign();
133-
$campaign->name = 'Campaign #' . time();
134-
$campaign->status = 'ACTIVE';
135-
$campaign->biddingStrategyConfiguration = new BiddingStrategyConfiguration();
136-
$campaign->biddingStrategyConfiguration->biddingStrategyType = 'MANUAL_CPC';
137-
$campaign->budget = new Budget('DAILY', new Money(50000000), 'STANDARD');
138-
139-
$operation = new CampaignOperation();
140-
$operation->operand = $campaign;
141-
$operation->operator = 'ADD';
142-
$operations[] = $operation;
143-
144-
// Add campaign.
145-
$campaignReturnValue = $campaignService->mutate($operations);
115+
```
116+
$user = new AdWordsUser('/config/myprops.ini');
146117
```
147118

119+
It is highly recommended that you use an **auth.ini** file. However, if you
120+
don't want to or can't use it, you can also set the same information using the
121+
`AdWordsUser` or `DfpUser` constructor. See the example for your product for
122+
details.
123+
124+
* AdWords - [CreateAdWordsUserWithoutIniFile.php](https://github.com/googleads/googleads-php-lib/blob/master/examples/AdWords/Auth/CreateAdWordsUserWithoutIniFile.php)
125+
* DFP - [CreateDfpUserWithoutIniFile.php](https://github.com/googleads/googleads-php-lib/blob/master/examples/Dfp/Auth/CreateDfpUserWithoutIniFile.php)
126+
127+
148128
### How do I set different client customer IDs than specified in auth.ini?
149129

150-
You can do this by calling `SetClientCustomerId()` of an `AdWordUser` object
151-
with a parameter as client customer ID you want to set to:
130+
You can do this by calling `SetClientCustomerId()` on an `AdWordsUser`:
152131

153132
```php
154133
// Create an AdWordsUser instance using the default constructor, which will load
@@ -157,22 +136,22 @@ $user = new AdWordsUser();
157136
$user->SetClientCustomerId('INSERT_CLIENT_CUSTOMER_ID_HERE');
158137
```
159138

160-
### How do I enable logging?
139+
### Configuring logging
161140

162-
The client library uses a custom class for all logging purposes and is exposed
163-
through the Logger.php file. There are two loggers within this class described
141+
The client library uses a custom class for all logging purposes that is exposed
142+
through the [Logger.php](https://github.com/googleads/googleads-php-lib/blob/master/src/Google/Api/Ads/Common/Util/Logger.php)
143+
file. There are two loggers within this class described
164144
below.
165145

166-
- REQUEST_INFO_LOG: Logs all requests from the client library along
167-
with information such as the timestamp, email, service, method,
168-
request Id, response time and which server was used. The default
169-
behavior is to log this information to "request_info.log" relative to
170-
your project's home directory.
146+
- REQUEST_INFO_LOG: Logs all requests from the client library along with
147+
information such as the timestamp, email, service, method, request ID,
148+
response time and which server was used. The default behavior is to log this
149+
information to "request_info.log" relative to your project's home directory.
171150

172151
- SOAP_XML_LOG: Logs all incoming and outgoing SOAP requests/responses. The
173-
default behavior is to log this information to "soap_xml.log" relative
174-
to your project's home directory. Sensitive information, such as
175-
authentication tokens, will be stripped.
152+
default behavior is to log this information to "soap_xml.log" relative to
153+
your project's home directory. Sensitive information, such as authentication
154+
tokens, will be stripped.
176155

177156
Logging can be enabled using the following methods.
178157

@@ -187,30 +166,43 @@ Logging can be enabled using the following methods.
187166
You can use the methods of the Logger class directly for even more control over
188167
how requests are logged.
189168

190-
### Notes about using composer.json
169+
### Documentation
191170

192-
As there are some classes declared with the same names in each version directory
193-
under `src/Google/Api/Ads/AdWords/Util`, this path cannot be included in
194-
`classmap` of `composer.json`.
171+
PHPDoc for this library can be found in the
172+
[gh-pages](https://github.com/googleads/googleads-php-lib/tree/gh-pages) branch
173+
of this repository and can be viewed at:
195174

196-
Thus, if you use composer, you will still need to manually copy over the version
197-
of the utility files you need to use.
198-
For instance, if you use `classmap` and v201601 of this library, you may add the
199-
following to your project's `composer.json`:
175+
* [AdWords](http://googleads.github.io/googleads-php-lib/AdWords)
176+
* [DFP](http://googleads.github.io/googleads-php-lib/Dfp)
200177

201-
```json
202-
"classmap": [
203-
"vendor/googleads/googleads-php-lib/src/Google/Api/Ads/AdWords/Util/v201601"
204-
]
205-
```
178+
General AdWords and DFP API documentation can be found on our Developers site.
179+
180+
* [AdWords API documentation](https://developers.google.com/adwords/api)
181+
* [DFP API documentation](https://developers.google.com/doubleclick-publishers)
182+
183+
### Getting support
184+
185+
For client library specific bug reports, feature requests, and patches, please
186+
create an issue on the
187+
[issue tracker](https://github.com/googleads/googleads-php-lib/issues).
188+
189+
For general AdWords and DFP API questions, bug reports, or feature requests,
190+
please post to our API forums:
191+
192+
* [AdWords API Forum](https://groups.google.com/group/adwords-api)
193+
* [DoubleClick for Publishers API Forum](https://groups.google.com/forum/#!forum/google-doubleclick-for-publishers-api)
194+
195+
### Announcements and updates
206196

207-
We are working on rewriting this library with namespacing and PSR-4 support.
208-
The progress and discussion of this work can be found at issue
209-
[#4](https://github.com/googleads/googleads-php-lib/issues/4).
197+
For general ads API and client library updates and news, please follow or join
198+
our:
210199

211-
### Where do I submit client library bug reports, feature requests, and patches?
200+
* [Google+ Ads Developers page](https://plus.google.com/+GoogleAdsDevelopers/posts)
201+
* [Google Ads Developers blog](http://googleadsdeveloper.blogspot.com)
202+
* [AdWords API Announcements mailing list](https://groups.google.com/forum/#!forum/adwordsapi-announcements)
203+
* [DFP API Sunset Announcements mailing list](https://groups.google.com/forum/#!forum/dfpapi-sunset-announce)
212204

213-
All of these can be submitted through the
214-
[issue tracker](https://github.com/googleads/googleads-php-lib/issues) in this
215-
GitHub project.
205+
API deprecation schedules can be found at:
216206

207+
* [AdWords API deprecation schedule](https://developers.google.com/adwords/api/docs/sunset-dates)
208+
* [DFP API deprecation schedule](https://developers.google.com/doubleclick-publishers/docs/deprecation)

0 commit comments

Comments
 (0)