# PHP Connector

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

> $ composer require digitsrl/php-wom-connector

This will automagically install all packages required by the Connector.

## Voucher generation
The process of generating WOMs is pretty straightforward.
You just need to be sure to comply with the requirements detailed in section [Instrument - What you need](# "Instrument - What you need").

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

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

and **optionally** enabling the DEV configuration.
DEV configuration can be used to test your software in a protected environment. Basically, this flag enables the debug output and force all the remote requests to be issued to the `dev.wom.social` end-points instead of the usual `wom.social`.

DEFINE("DEV", True); // This enables DEV 

Once you're done experimenting, just delete it for production configuration.

### 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: if your key is password-protected, you can optionally pass the password along with the other parameters.

// INSTRUMENT CREATION
// Instantiate the Instrument with its ID, Private Key, and (optionally) the private key's password

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

### Generating Vouchers' specification
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 WOMs.

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

try{
    $Instrument->RequestVouchers($vouchers,  "", $pin, $otc);
    echo "Otc: {$otc} Pin:{$pin}";

}catch(Exception $exception) {

    echo "No voucher generated :(";
}

Optionally, you can also use a utility method which comes with the connector to generate a QRCode PNG. You just need to provide the `OTC`, the expected size of the image, and its full path:

try{
    $Instrument->RequestVouchers($vouchers,  "", $pin, $otc);
    echo "Otc: {$otc} Pin:{$pin}";
    
    \WOM\WOMQRCodeGenerator::GetQRCode($otc, 300, "vouchers.png");
    
}catch(Exception $exception) {
    echo "No voucher generated :(";
}

That's it!

And here is the complete code:

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

DEFINE("INSTRUMENT_PRIVATE_KEY", "path/to/instrument/key.pem");
DEFINE("INSTRUMENT_PRIVATE_KEY_PASSWORD", "optional-key-password");
DEFINE("INSTRUMENT_ID", "5e737fbahas6edb02d61ef6d"); //dummy

DEFINE("DEV", True); // This enables DEV configuration. Delete it for production configuration.

date_default_timezone_set("UTC"); //WOM server uses default UTC timezone.

// VOUCHER GENERATION
// Generate 10 vouchers with 3 different aims
$vouchers = array();
$available_aims = array('H', 'C', 'I');
for($i=0; $i < 10; $i++){
    $aim = $available_aims[$i%3];
    $vouchers[] = \WOM\Voucher::Create($aim, 42.4564, 12.5263, new DateTime('NOW'));
}

// or, if they have identical aim, coordinates, and timestamp, you can generate them using the $count optional parameter
$vouchers[] = \WOM\Voucher::Create('H', 42.4564, 12.5263, new DateTime('NOW'), 10);


// INSTRUMENT CREATION
// Instantiate the Instrument with its ID, Private Key, and (optionally) the private key's password
$Instrument = new \WOM\Instrument(INSTRUMENT_ID, INSTRUMENT_PRIVATE_KEY, INSTRUMENT_PRIVATE_KEY_PASSWORD);

// Request Vouchers
$otc = null;
$pin = null;

try{
    $Instrument->RequestVouchers($vouchers,  "", $pin, $otc);
    echo "Otc: {$otc} Pin:{$pin}";

    \WOM\WOMQRCodeGenerator::GetQRCode($otc, 300, "path/to/vouchers.png");
    
}catch(Exception $exception) {
    echo "No voucher generated :(";
}

Enjoy your WOMs :+1:

---

## Payment Request generation
The process of generating Payment Requests is even more straightforward than the WOM generation process.
Please, be sure to comply with the requirements detailed in section [POS - What you need](# "POS - What you need").

Initially, you need to import the connector library, including the autoload script generated by Composer, just like for the [Voucher Generation procedure](#voucher-generation).

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

### Creating a POS
Instantiate your POS by providing its *Id* and its *Private Key*.
**Note**: just like the Instrument, if your key is password-protected, you can optionally pass the password along with the other parameters.
**Note 2**: usually, POS and Instrument, even is they belong to the same entity, have different Ids and Keys.

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

### Generating a Payment Filter
To obtain a Payment Request you usually only need the amount of WOMs to be paid.
Optionally, you can also specify a Filter and an HTTPS end-point.

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:
* The vouchers' maximum age. E.g., Vouchers older than 7 days can't be accepted.
* A geographical (rectangular) bounding box. Only Vouchers earned within the specified area are allowed.
* An Aim code to filter out vouchers earned volunteering towards other public aims.

Creating a Filter is pretty simple. All parameters are optional.

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

In case you can accept any kind of vouchers as a payment, you still need to provide an empty Payment Filter:

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

The optional HTTPS end-point can be specified for receiving payment acknoledgements.

### Generating Payment Requests

You are just a method invocation away from generating a proper Payment Request.
Just call the `RequestVouchers` method as done below:

try{
    $POS->RequestPayment(100,           // amount of vouchers
        'http://pocket-server.org',     // pocket acknoledgement URL
        $filter,                        // the (possibily empty) filter
        'http://pos-server.org',        // optional POS acknoledgement URL
        False,                          // is it a persistent payment?
        null,                           // optional nonce (automatically generated if left empty)
        $password,                      // output parameter
        $otc);                          // output parameter
    echo "Otc: {$otc} Pin:{$pin}";

}catch(Exception $exception) {

    echo "No payment generated :(";
}

Just like the Voucher generation process you can also use a utility method which comes with the connector to generate a QRCode PNG. You just need to provide the `OTC`, the expected size of the image, and its full path:

try{
    $POS->RequestPayment(100,           // amount of vouchers
        'http://pocket-server.org',     // pocket acknoledgement URL
        $filter,                        // the (possibily empty) filter
        'http://pos-server.org',        // optional POS acknoledgement URL
        False,                          // is it a persistent payment?
        null,                           // optional nonce (automatically generated if left empty)
        $password,                      // output parameter
        $otc);                          // output parameter
    echo "Otc: {$otc} Pin:{$pin}";
    
    $QRCode = \WOM\WOMQRCodeGenerator::GetQRCode($otc, 300, "path/to/payment_request.png");
    echo $QRCode;

}catch(Exception $exception) {

    echo "No payment generated :(";
}

And that's the complete code:

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

DEFINE("POS_PRIVATE_KEY", "path/to/pos/key.pem");
DEFINE("POS_PRIVATE_KEY_PASSWORD", "optional-key-password");
DEFINE("POS_ID", "5e737fbahas6edb02d61ef6d"); //dummy

DEFINE("DEV", True); // This enables DEV configuration. Delete it for production configuration.

date_default_timezone_set("UTC"); //WOM server uses default UTC timezone.

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

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


// Request Vouchers
$otc = null;
$password = null;


try{
    $POS->RequestPayment(100,           // amount of vouchers
        'http://pocket-server.org',     // pocket acknoledgement URL
        $filter,                        // the (possibily empty) filter
        'http://pos-server.org',        // optional POS acknoledgement URL
        False,                          // is it a persistent payment?
        null,                           // optional nonce (automatically generated if left empty)
        $password,                      // output parameter
        $otc);                          // output parameter
    echo "Otc: {$otc} Pin:{$pin}";
    
    $QRCode = \WOM\WOMQRCodeGenerator::GetQRCode($otc, 300, "path/to/payment_request.png");
    echo $QRCode;

}catch(Exception $exception) {

    echo "No payment generated :(";
}