Extension:DonationInterface

DonationInterface provides fundraising mechanisms for collecting and tracking payments through various payment gateways.

Fundraiser 2011 Development
Prior to Fundraiser 2011 development, the only heavily-used payment gateway was Payflow Pro (Paypal's Credit Card Processor). In an effort to allow new gateways to be easily added to DonationInterface, much of the code is being abstracted out into modular objects, with the goal of having all the gateway-specific structures and logic contained in a few files.

All refactoring work is being done in the fundraiser's Donation Interface branch.

New Installation Procedure
Prior to the refactoring, it was necessary to include the installation files for several subdirectories as if they were standalone extensions. After the refactoring is complete, the installation will be simpler than it was before. Include the following line in LocalSettings.php: require_once( "$IP/extensions/DonationInterface/donationinterface.php" );

After this, be sure to redefine the global variables for each gateway you intend to use. Particularly, the MerchantID and Password.

Additionally, the refactored DonationInterface requires Extension:ContributionTracking to be installed and configured: DonationInterface now uses a number of static ContributionTracking functions to record relevant donation tracking data.

Define Globals in LocalSettings.php
While there are many more globals available to override, the following probably need to be defined in LocalSettings if you want DonationInterface to actually work. The majority of additional global variables of interest can be found in donationinterface.php, /payflowpro_gateway/payflowpro_gateway.php, and /globalcollect_gateway/globalcollect_gateway.php. NOTE: There is a slight timing issue in the installation process here, so order totally matters. In general, it is probably a good idea to define your donationinterface globals before you define your gateway-specific globals.

Changed Global Variables
All gateways in DonationInterface now have a standardized global variable prefix, so GatewayAdapter::getGlobal works properly. This necessitated a number of global variable name changes.

Anywhere these old values are encountered in the code, they should be changed to the new values. For the most part, these have been changed in places where the whole page isn't about to be refactored into near-oblivion.

The current list of global variable name changes is as follows:

Things That Have Moved
The basic idea is that we'd pop everything that is of more universal use, out of the payflowpro_gateway directory. Here is a short list of things that have moved.
 * The directory that used to be located under DonationInterface/payflowpro_gateway/forms has been moved to DonationInterface/gateway_forms. Any references to DonationInterface/payflowpro_gateway/forms need to be changed.
 * All the form classes have been changed to reflect their newfound freedom from PayflowPro, and are now added to $wgAutoloadClasses out in donationinterface.php. (Though the forms have yet to be freed from PFP's globals)

New Structure
So far, there are two new classes.

GatewayAdapter class
This is an abstract class that takes care of everything a general gateway needs to do. It it also supposed to yell at you rather loudly if you fail to define any of the particulars that a gateway needs, in order to be able to do anything worthwhile.

Clearly there should be more here.

DonationData class
This class is intended to handle everything that we are likely to want to do with Donation Data. It should load the data in a consistent way from any appropriate source (including a test), saves relevant Contribution Tracking data, generates data we always need to generate (like order IDs), normalises everything, and hands it back to the gateway. It also handles edit tokens.

Ongoing Work
Now we've gotten a decent foothold on this campaign of abstraction, at least half of this thing is a busted mess. We're fixing it; General plan forthcoming.

Meanwhile, here is a list.
 * Change all the messages in an intelligent way. Lots of generally useful-type messages live in Payflow Pro's i18n somewhere, and they need to be popped out a level in a way that won't cause translatewiki to explode (much).
 * The forms (and the bits of DonationInterface that touch them directly) need love.
 * PayflowPro needs to be made to use the new GatewayAdapter class. See the globalcollect gateway for an example of how it ought to look when it's done.
 * Test coverage!
 * Make all the gateway functionality accessible via API. (Should be pretty trivial for gateways that use the new classes)
 * Actually handle the processing of the return data in the GatewayAdapter class (and children where appropriately specific to that particular gateway). Probably just another array variable map of their values to ours in the gateway child class, and a general return value handler in GatewayAdapter.

Unit Testing
Unit tests can be found in the tests directory of the DonationInterface extension.

To run unit tests go to the directory where you have extension checked out. Here is an example:

cd /www/sites/localhost/wikimedia-fundraising.localhost.wikimedia.org

cd extensions/DonationInterface/tests

Unit testing can be run with a few extra options:

Run all DonationInterface unit tests with TestDox:

../../../tests/phpunit/phpunit.php --testdox-html /tmp/testdox.DonationInterface.html AllTests.php

With TestDox and the group BankTransfer:

../../../tests/phpunit/phpunit.php --group BankTransfer --testdox-html /tmp/testdox.DonationInterface.html AllTests.php

You can also get code coverage. The path to code coverage is a relative path.

../../../tests/phpunit/phpunit.php --testdox-html /tmp/testdox.DonationInterface.html --coverage-html coverage AllTests.php

You can also run debugging to see which test methods are being run:

../../../tests/phpunit/phpunit.php --debug --testdox-html /tmp/testdox.DonationInterface.html --coverage-html coverage AllTests.php

You can view the code coverage report by going to your local Mediawiki instance:

http://wikimedia-fundraising.localhost.wikimedia.org/extensions/DonationInterface/tests/coverage/

The above testing methods work on trunk, not 1.17. For 1.17 here is an example:

/www/library/phpunit/phpunit/phpunit.php --verbose --debug --coverage-html coverage/html --coverage-clover coverage/clover/index.xml --testdox-html coverage/html/testdox.html AllTests

To specify a group:

/www/library/phpunit/phpunit/phpunit.php --verbose --debug --coverage-html coverage/html --coverage-clover coverage/clover/index.xml --testdox-html coverage/html/testdox.html --group BankTransfer AllTests