Issue #112 Recode Sage Pay Form data from UTF-8 to ISO8859-1 by default.

Provide an option to disable this for when the merchant site handles
it already. In the vast number of cases, the conversion should stand.
That is, until Sage Pay get their ISO8859 technical debt sorted out
for good.

Author: judgej

README.md

@@ -622,6 +622,15 @@ $gateway = OmniPay::create('SagePay\Form')->initialize([
 
 The `encryptionKey` is generated in "My Sage Pay" when logged in as the administrator.
 
+Note that this gateway will assume all inout data (names, addresses etc.)
+are UTF-8 encoded.
+It will then recode the data to ISO8859-1 before encrypting it for the gateway,
+as the gateway strictly accepts ISO8859-1 only, regardless of what encoding is
+used to submit the form from the merchant site.
+If you do not want this conversion to happen, it can be disabled with this parameter:
+
+    'disableUtf8Decode' => true,
+
 The authorize must be given a `returnUrl` (the return URL on success, or on failure
 if no separate `failureUrl` is provided).
 
@@ -639,10 +648,11 @@ At the gateway, the user will authenticate or authorise their credit card,
 perform any 3D Secure actions that may be requested, then will return to the
 merchant site.
 
-To get the result, the transaction is "completed":
+To get the result details, the transaction is "completed":
 
 ```php
-// The result will in read and decrypted from the return URL query parameters:
+// The result will be read and decrypted from the return URL (or failure URL)
+// query parameters:
 
 $result = $gateway->completeAuthorize()->send();
 
@@ -651,6 +661,14 @@ $result->getTransactionReference();
 // etc.
 ```
 
+If you already have the encrypted response string, then it can be optionally
+passed in:
+
+    $result = $gateway->completeAuthorize(['crypt' => $crypt])->send();
+
+This should normally not be necessary, but is handy for testing or if the
+current page query parameters are not available in a particular architecture.
+
 ### Form Purchase
 
 This is the same as `authorize()`, but the `purchase()` request is used instead,

src/Message/Form/AuthorizeRequest.php

@@ -189,18 +189,26 @@ public function generateCrypt(array $data)
 
         // Build the data in a query string.
 
-        // CHECKME: what happens with UTF-8 data? Do we need to convert
-        // any special characters not in the correct ranges?
-        // What about options for URL encoding of other characters?
+        // The encrypted data MUST be ISO8859-1 regardless of what encoding
+        // is used to submit the form, because that is how the gateway treats
+        // the data internally.
+        // This package assumes input data will be UTF-8 by default, and will
+        // comvert it accordingly. This can be disabled if the data is already
+        // ISO8859-1.
+        // For the Server and Direct gateway methods, the POST encoding type
+        // will tell the gateway how to interpret the character encoding, and
+        // the gateway will do any encoding conversions necessary.
 
         // We cannot use http_build_query() because the gateway does
         // not decode the string as any standard encoded query string.
         // We just join the names and values with "=" and "&" and the
         // gateway somehow decodes ambiguous strings.
 
+        $disableUtf8Decode = (bool)$this->getDisableUtf8Decode();
+
         $query = [];
         foreach ($data as $name => $value) {
-            $query[] = $name . '=' . $value;
+            $query[] = $name . '=' . ($disableUtf8Decode ? $value : utf8_decode($value));
         }
         $query = implode('&', $query);
 

src/Traits/GatewayParamsTrait.php

@@ -237,4 +237,24 @@ public function setBillingForShipping($value)
     {
         return $this->setParameter('billingForShipping', $value);
     }
+
+    /**
+     * @return mixed
+     */
+    public function getDisableUtf8Decode()
+    {
+        return $this->getParameter('disableUtf8Decode');
+    }
+
+    /**
+     * The Form API will convert all input data from an assumed UTF-8
+     * encoding to ISO8859-1 by default, unless disabled here.
+     *
+     * @param mixed $value Will be evaluated as boolean.
+     * @return $this
+     */
+    public function setDisableUtf8Decode($value)
+    {
+        return $this->setParameter('disableUtf8Decode', $value);
+    }
 }