Fundraising/tech/Transformer

This is a draft specification for a data transformation component to be used throughout Fundraising.

Background

Many Fundraising libraries need to perform similar transformations between internal (normalized) and 3rd-party API representations of donor and donation data. Wherever possible, we want to extract the gateway-specific transformations into their own component, so that these transformations are applied in a consistent way across codebases. Ideally, the transformation would be described using declarative data except in the few cases where we need custom code.

Currently, this code will be found in DonationInterface, crm, audit scripts, and listeners.

Implementation

FieldTransformation

A first-class object that describes how to map a small unit of data from one system to another. Try to keep each of these as small as possible, for reuse. This may map a field 1:1 between the systems, perform validations, or do 1-many, or many-1. It is passed all the data in the input array, and the output array in whatever state it has reached.

API:

• run($in, &$out), throws ValidationException

Transformer

A container holding a list of FieldTransformations. A Transformer object is usually obtained from the gateway, and is specific to a mapping from one system to another. We probably want a factory interface.

Request Mush

This is ill-defined at the moment. We realized there is a need for gateway-specific logic that can combine GET, POST, and SESSION data using precedence rules. We think it's best if this logic is run on normalized data only.

Data System

Examples of data systems: 'user:ccform', 'api:DoPayment', 'crm', 'audit:TrrFile', 'normal', 'listener'...