/php-oara

Open Affiliate Report Aggregator

Primary LanguagePHPGNU Affero General Public License v3.0AGPL-3.0

php-oara

The goal of the Open Affiliate Report Aggregator (OARA) is to develop a set of PHP classes that can download affiliate reports from a number of affiliate networks, and store the data in a common format.

We provide a simple structure and make it easy to add new networks using the tools available.

This project is being used as part of AffJet, which offers a hosted Affiliate Aggregator service, with a web interface and additional analysis tools.

Development is sponsored by AffJet but we welcome code contributions from anyone.

License

PHP-OARA is available under a dual license model; either AGPL or a commercial license, depending on your requirements. If you wish to use php-oara in an open source project, or one for internal use only then you can choose the AGPL. If you wish to use php-oara in a commercial project that will be available to external users, then you should contact us for a commercial license.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License (LICENSE.TXT).

If you are interested in being a contributor to this project we encourage to read, fill and send this file (FubraLimited-ContributorLicenseAgreement.docx) to support@fubra.com.

Networks Supported

The list of supported networks for Publishers so far is:

The list of supported networks for Advertisers so far is:

System Requirements

To run php-oara you will need to use PHP 5.3, and enable the CURL extension in your php.ini.

Also you will need to have GIT installed in your computer.

Getting Started

Once you have finished these steps you will be able to run the examples for the different networks.

Follow the steps

1. Create the folder with the clone of the code.

git clone https://github.com/fubralimited/php-oara.git php-oara

2. Change the directory to the root of the project

cd php-oara

3. Initialise composer

curl -s https://getcomposer.org/installer | php --
php composer.phar self-update
php composer.phar install

5. Credentials.ini.sample

In the example folder a "credentials.ini.sample" has been provided.
Please rename it to "credentials.ini" and follow the intructions
in order to fill your crendentials.

PHP OARA on Composer

You can use the package "fubralimited/php-oara" from composer instead to import the library.

Contributing

If you want to contribute, you are welcome, please follow the next steps:

Create your own fork

  1. Follow the next instructions to fork your own copy of php-oara. Please read it carefully, as you can also follow the main branch in order to request the last changes in the code.

  2. Work on your own repository. Once all the code is in place you are free to add as many networks and improve the code as much as you can.

  3. Send a pull request instructions When you think that your code is finished, send us a pull request and we will do the rest!

Follow the structure

We would like you to follow the structure provided. If you want to add a network, please pay attention to the next rules:

  • Create a class in the Oara/Network folder with the name of the network. This class must implement the Oara_Network Interface

  • Implement the methods needed:

    • checkConnection
    • getMerchantList
    • getTransactionList
    • getPaymentHistory
    • paymentTransactions
  • Add the credentials to the credentials.ini.sample. (Please add also information about how to find your credentials)

  • Add the generic example to the examples folder.

Network

The network classes must implement the Oara_Network interface, which includes these methods.

checkConnection()

It checks if we are succesfully connected to the network

return boolean (true is connected successfully)

getMerchantList()

Gets the merchants joined for the network

  • return Array ( Array of Merchants )

getTransactionList(array $merchantList, Zend_Date $dStartDate, Zend_Date $dEndDate, array $merchantMap)

Gets the transactions for the network, from the "dStartDate" until "dEndDate" for the merchants provided

  • @param array $merchantList - array with the merchants unique id we want to retrieve the data from

  • @param Zend_Date $dStartDate - start date (included)

  • @param Zend_Date $dEndDate - end date (included)

  • @param array $merchantMap - array with the merchants indexed by name, only in case we can't get the merchant id in the transaction report, we may need to link it by name.

  • return Array ( Array of Transactions )

getPaymentHistory()

Gets the Payments already done for this network

  • return Array ( Array of Payments )

paymentTransactions($paymentId, $merchantList, $startDate)

Gets the Transactions Id for a paymentId

  • @param array $paymentId - Payment Id of the payment we want the trasactions unique_id list.

  • @param array $merchantList - array with the merchants we want to retrieve the data from

  • @param Zend_Date $startDate - start date ,it may be useful to filter the data in some networks

  • return Array ( Array of Transcation unique_id )

Merchant

It's an array with the following keys:

  • name (not null) - Merchant's name

  • cid (not null) - Merchant's unique id

  • description - Merchant's description

  • url - Merchant's url

Transaction

It's an array with the following keys:

  • merchantId (not null) - Merchant's unique id

  • date (not null) - Transaction date format, "2011-06-26 18:10:10"

  • amount (not null) - Tranasction value (double)

  • commission (not null) - Transaction commission (double)

  • status (not null) - Four different statuses:

    • Oara_Utilities::STATUS_CONFIRMED
    • Oara_Utilities::STATUS_PENDING
    • Oara_Utilities::STATUS_DECLINED
    • Oara_Utilities::STATUS_PAID
  • unique_id - Unique id for the transaction (string)

  • custom_id - Custom id (or sub id) for the transaction (string), custom param you put on your links to see the performance or who made the sale.

Payment

It's an array with the next keys:

  • pid (not null) - Payment's unique id

  • date (not null) - Payment date format, "2011-06-26 18:10:10"

  • value (not null) - Payment value

  • method (not null) - Payment method (BACS, CHEQUE, ...)

Contact

If you have any question, go to the project's website or send an email to support@affjet.com