README

Setup

Installation of the PHP WOM Connector is only a Composer command away:

composer require digitsrl/php-wom-connector:dev-master

This will automatically install all packages required by the Connector and check compatibility with your setup.

Configuration

Check out /test/example_instrument.php, /test/example_pos.php, and /test/example_check.php files for samples of how to use the connector.

It is suggested to set the default timezone to UTC before using the Connector.

date_default_timezone_set("UTC");

By default, the WOM Connector sets up an internal logger that writes informative messages to STDERR, but you can customize the logging handlers using the Initialize method (which takes a single handler or an array of Monolog handlers):

\WOM\Logger::Initialize(array(
    new \Monolog\Handler\StreamHandler('php://stdout', \Monolog\Logger::DEBUG)
));

WOM vouchers can be generated on different domains, with different (and custom) Registry installations. By default, the Connector picks the standard Registry, which lives on the official wom.social domain. You can customize this using the following configuration line:

\WOM\Config\Domain::SetDomain('dev.wom.social');

When developing your new WOM Platform integration, it can be useful to test on the development domain dev.wom.social (contact the WOM development team about this). The POS/Instrument keys and IDs that are used in the test scripts can be freely used on the development domain.

Voucher generation

The process of generating WOMs is pretty straightforward. You just need to be sure to comply with the requirements of the Platform and be registered as a WOM "Instrument".

The very first step is to import the connector library, including the autoload script generated by Composer.

require __DIR__ . '/vendor/autoload.php';

Creating an Instrument

To generate WOMs you need to instantiate an Instrument. To do that, you will need the Id and the Private Key associated with your Instrument. Note that the second parameter contains the path to the key file (.pem).

$instrument = new \WOM\Instrument(
    INSTRUMENT_ID,
    INSTRUMENT_PRIVATE_KEY,
    INSTRUMENT_PRIVATE_KEY_PASSWORD
);

Note: if your key is password-protected, you can optionally pass the password along with the other parameters. Otherwise, pass in NULL or an empty string.

Generating voucher specifications

To request WOMs you need to specify what kind of information you need them to contain. Since multiple vouchers can be requested at once, you need to instantiate an array of voucher specifications.

In this case, we populate the array with just one type of voucher:

$vouchers[] = \WOM\Voucher::Create('H', 40.12319, 12.83548, new DateTime('NOW'));

In case you need many identical vouchers you can specify their quantity with the additional parameter count:

$vouchers[] = \WOM\Voucher::Create('H', 40.12319, 12.83548, new DateTime('NOW'), 100);

Here we are asking for 100 WOM vouchers.

Perform the request

You are almost done! You just need to actually request the vouchers. If the request is successful the server response will contain the OTC and the Password which you should present to your users in order to allow them to redeem the WOMs they earned.

$values = $instrument->RequestVouchers($vouchers);

$otc = $values['otc'];
$pin = $values['password'];

The full example is in example_instrument.php.

Payment request generation

The process of generating payments for the WOM Platform is very similar to the voucher generation process: please follow the same setup and autoload steps.

Creating a Point of Service

Just like when instantiating Instruments, you can instantiate your POS by providing its Id and its Private Key:

$POS = new \WOM\POS(
    POS_ID,
    POS_PRIVATE_KEY,
    POS_PRIVATE_KEY_PASSWORD
);

Note: just like above, the private key parameter contains the path to the key file. Also, even if POS and Instrument belong to the same entity, they will have different IDs and keys.

Generating a payment filter

To obtain a payment request you usually only need to specify the amount of WOMs to be paid. However, you may also specify a filter that will be used to select which WOM vouchers are valid for payment and which are not.

Providing a payment filter makes you able to choose which kind of vouchers can be used to pay your services. Filters can be comprised of one or more of the following elements:

Maximum age: the maximum amount of days between now and when the vouchers were generated. Vouchers that are older than the set amount of days will not be accepted.
Geographical region: a geogrphical (rectangular) bounding box. Only vouchers earned within the specified area are allowed (notice that the region is specified as a couple of coordinates, top left and bottom right, both of which are expressed as an array of numbers, latitude and then longitude).
Aim: setting an aim code filters out vouchers that volunteers earned by contributing to other public aims. Note that aim codes are hierarchical, so filtering on ‘H’ will accept any voucher with an aim starting with the same letter (for instance ‘HE’).

All parameters are optional:

$filter = \WOM\Filter::Create('H', array(46.0, -17.0), array(12.0, 160.0), 14);

In case you want to accept any kind of vouchers as a payment, you still need to provide an empty filter:

$filter = \WOM\Filter::Create();

Generating the request

You are just a method invocation away from generating a proper payment request. Just call the RequestVouchers method as shown below:

$values = $POS->RequestPayment(
    100, // Number of WOM vouchers required to perform payment
    'https://myserver.io/confirm/uniquecode123', // Pocket confirmation URL, will be opened by Pocket on payment completion, can be null if Pocket should only display payment confirmation on screen
    $filter, // Filter that determines which vouchers are accepted
    'https://myserver.io/backend/confirm', // Optional Registry confirmation URL, which receives a webhook request from the Registry on payment completion, can be null
    null // Optional boolean indicating whether this is a persistent payment (can be performed multiple times) or not
);

$otc = $values['otc'];
$pin = $values['password'];

The full example is in example_pos.php.

digitsrl / php-wom-connector

Maintainers

Details