Download the PHP package adprolabs/easy-adwords without Composer

EasyAdWords is an easy-to-use and customizable library that simplifies the basic usage cases of the AdWords API with PHP Client library v25.3 currently. It basically allows simpler reporting process with downloading and parsing the report, and also allows entity operations such as getting, creating and removing campaigns, ad groups and keywords.

For example, an Account Performance Report can easily be downloaded and formatted like the following simple snippet:

Table of Contents

• Installation
• Auth
• Config
  • Required Fields
  • Optional Fields
• Reporting
• Entities
  • Account
  • Campaign
  • AdGroup
  • Keyword
  • Keyword
  • KeywordBatch
• Contribution
• License

Installation

composer require adprolabs/easy-adwords

Auth

Most of the package is developed with the user is logged in via Google in mind. Therefore, there are some helpers for authentication process in EasyAdWords. First of all, you need client ID and client secret, instructions about that can be found here with more details about the authentication process. After you created your client ID and secret, you can use them to create an oAuth object and then use it to register your user.

Assume that you used this part in constructor, which means this is used for both redirecting and callback parts:

This part is for redirection to the Google now:

After the user is redirected to the Google and allowed your application to access data, Google will redirect the user to your "redirectUri" address, which needs to be the callback. An example callback can be as follows:

This is it, now you have your access token and refresh token in the $credentials parameter and you downloaded the customers of the account, now you can do whatever you want. Note that, the $this->authObject->buildOAuthObject($this->config); line returns an instance of Google\Auth\OAuth2 object, therefore you can use any methods of it with the object and also get help from the AdWords API documentation.

Config

Basically, EasyAdWords aims to create an easy-to-use interface between the developer and the AdWords PHP Client library. In order to keep this process simple, EasyAdWords uses configuration objects across different entities and operations. All of these config objects are specialized for the service they are used with; however, they all extend the base Config class.

Required Fields

The Config class contains the following fields as required, since they are required for every service used with EasyAdWords:

• adwordsConfigPath => The path to the AdWords config file. If this is not given, the package looks for adsapi_php.ini file in the project root.
• clientCustomerId => ID of the customer to operate on. Required.
• refreshToken => Refresh token of the authenticated user. Required.
• fields => Fields to get. Required for get operations.

Keep in mind that these fields are required for all of the config objects, except that the adwordsConfigPath key, which seems to be not necessary, however if not given, the AdWords PHP Client library will look for the adsapi_php.ini file in the project root, therefore it is required to have this file.

Optional Fields

The following are optional values that can be used with any config object for entity operations. Note that reporting does allow pagination to be used, instead you need to filter your reports with appropriate predicates if the response was too large.

• paginated => Boolean value to determine if the operation will be performed page by page, useful if you get SizeLimitError.RESPONSE_SIZE_LIMIT_EXCEEDED error with a get operation on an entity.
• pageSize => Page size for the get operations, default is 10000, the maximum number allowed.

Reporting

EasyAdWords contains some basic classes that allows to get reports from AdWords easily. The following are available reporting classes for now:

• AccountPerformanceReport
• AdGroupPerformanceReport
• AdPerformanceReport
• CampaignPerformanceReport
• CustomReport
• FinalUrlReport
• KeywordsPerformanceReport
• SearchQueryPerformanceReport

All of these classes implement the same interface, therefore they all have the same methods to use. Basically, all of these report classes need to construct the report objects with a ReportConfig instance. An example ReportConfig object is as follows:

This ReportConfig object is constructed over a simple array. Available fields for the array are as follows:

• startDate => Start date of the report. Required.
• endDate => End date of the report. Required.
• predicates => Predicates to filter the report.

The report object can now be initialized with the newly created ReportConfig object. After creating the report instance, we can simply call download() and format() methods on the object in order to download the report as CSV and format it to a simple, one-dimensional array respectively. An example usage is as follows:

This process is same for all of the reports. In addition to the available report classes, one can simply create a custom report by using the CustomReport class with the same config objects and methods. The only difference is, using a custom report, there needs to be a parameter given to the download() method of the report object, indicating the type of the report. The parameter given must be a constant from the ReportDefinitionReportType class of the AdWords PHP Client library. An example report using the same config object above is as follows:

Note that, after formatting the report, the CSV version of the report is not available.

Available methods for reports are as follows:

• download(): Downloads the report and stores it in the report property of the object.
• format(): Formats the CSV report into a flat array.
• saveToFile($filePath): Saves the report property of the object to the given file.
• downloadToFile($filePath): Downloads and stores the report in the given file path. Note that this method does not keep the report in the report object after downloading and writing to the file.

Entities

EasyAdWords offers basic entity operations for campaigns, ad groups and keywords. Basically, all of these three entities are able to perform 3 basic operations:

• create => Creates an instance of the entity in Google AdWords.
• get => Gets the instances of the entity that fits specified criteria.
• remove => Removes the instance of the entity from Google AdWords.

There is also an account entity, which only contains the get operation for now.

Basically, all of these entity objects operate with special config objects, just like the reporting objects. Therefore, an appropriate config object for the entity must be created, and then, the entity object can be constructed by using this config object.

All the entity objects are extending the base class Entity and implementing the EntityInterface. Therefore, after every operation, result of the operation is accessible as a property of the entity object, called operationResult, which can be accessed by using the method getOperationResult().

Available entities are Account, Campaign, Ad Group and Keyword for now. All the entities have their corresponding config objects, such as CampaignConfig.

The usage is same across the entity methods create, get and remove. As the nature of the get operation, the results can be filtered by specifying the predicates parameter, or can be ordered by ordering parameter. If there are no predicates set, all the instances of the entity will be listed. All the get operations will return an array of entity objects from Google AdWords PHP library, which can be used according to the Google AdWords API documentation. An example result is as follows for a get operation on Account entity:

Account

Account entity is the simplest entity in the package. It only contains a get method for the objects. The entity operates on an AccountConfig object, and this object must contain the fields parameter along with the required fields above, that determining the fields that will be returned from AdWords as the result.

An example usage is as follows:

Campaign

Like all the entities, the Campaign entity operates on a config object of the class CampaignConfig. The CampaignConfig class contains the following fields, in addition to the fields in the base Config class:

Not all these parameters are required for all of the campaign operations, some are needed for create operation, while some others are required for remove operation. However, if you do not provide some important properties, especially when creating a campaign, you will be facing with some errors. If you don't want to give every option for a campaign and use the defaults, just set useDefaults to true, and it will use the defaults. Keep in mind that, when creating a campaign, EasyAdWords sets the campaign status to 'PAUSED' in order to not to spend money on a misconfigured campaign on default, if otherwise is not stated. Also, you still need to provide a campaign name even with the defaults.

A basic usage of the campaign entity is as follows:

AdGroup

AdGroup entity is using the same simple set of methods and configuration logic. It works by using the AdGroupConfig object. The AdGroupConfig object consists of the following fields:

Some of these fields are required for some of the operations. For instance, campaignId, adGroupName and bid are required fields for creating an ad group.

A basic usage of the AdGroup entity is as follows:

Keyword

Keyword entity is a candidate for both singular and batch operations. Therefore, there are 2 different classes for Keyword entities. One of them is Keyword entity, which is used just like the Campaign and AdGroup entities; same set of methods and the same initialization process with KeywordConfig object. However, this class is intended to be used for singular entity operations, and in the case of keywords, this is not very useful. There is a need for batch keyword operations and AdWords Client library allows multiple operations to be sent over the same single request. Therefore, the second class KeywordBatch is implemented for batch keyword addition operations.

Both of these classes extend the same KeywordBase class.

Keyword

The Keyword class can be used with the same set of methods with other entities. It is initialized with the KeywordConfig object. The KeywordConfig object contains the following fields:

The usage of the class is almost the same with the other entities:

KeywordBatch

KeywordBatch class allows to create multiple keywords in the Google AdWords at once. The class is constructed over a simple KeywordBatchConfig object, which has only one additional value other than the required base values, batchSize. batchSize value determines how many of the keywords will be grouped into one request. The batch size can be at most 5000, however the AdWords API documentation recommends passing at most 2000 operation per request, therefore the default batch size is 2000 in KeywordBatchConfig objects.

The KeywordBatch object is simply constructed over the config object. After creating the instance, the object is ready to get the list of keywords. For each keyword to create, you need to create a KeywordConfig object in order to define the properties of the keyword and append this config object to the KeywordBatch object. This way, you can append as many keywords as you want to the batch object, and it will process all of those objects by batches of size batchSize. Note that the KeywordConfig objects to append a keyword do not need to contain the adWordsConfigPath, clientCustomerId and refreshToken parameters, as those were given in the KeywordBatchConfig object. In order to complete the operation and create keywords on Google AdWords, you need to call the method mutate() on the KeywordBatch object. Until you call the mutate() method, all the keywords will be just an array inside the object.

An example usage of KeywordBatch is as follows:

With the batch config class, you can create keywords in batches, thus decrease the network requests for creating keywords. The KeywordBatch class is only available for batch keyword addition operations for now.

Contribution

Your participation to EasyAdWords development in any form is very welcome! In order to contribute on the package, you need to clone the project and include it using the repositories option in your composer.json file. An example usage is as follows:

Note that repositories is in the same level with require key, not nested inside something else. The repositories option works with the vcs value in type. Therefore, in order to test the package in another project with including it as a package like above, you need to commit your changes on the package and then composer update on the test project in order to get the latest changes you have made.

After successfully updating the project with self-explanatory commit messages and adding comments to the code in PHPDoc style with proper explanations, you can submit a pull request with an explanation of why the update was required and what was your solution for this problem.

Also, you can contribute to EasyAdWords by creating an issue with a well-defined and reproducable problem or giving feedback about the package and its design. Any form of participation is very welcomed.

License

EasyAdWords is released under the MIT Licence. For further information, see the LICENSE.md.