Merge pull request #26 from PatronBase/master

Bundle of fixes/updates for WorldPay JSON Gateway
thephpleague · Oct 23, 2017 · 522fbac · 522fbac
2 parents be0b5c3 + 31cec5a
commit 522fbac
Show file tree

Hide file tree

Showing 18 changed files with 311 additions and 60 deletions.
diff --git a/README.md b/README.md
@@ -32,6 +32,7 @@ And run composer to update your dependencies:
 The following gateways are provided by this package:
 
 * WorldPay
+* WorldPay_Json
 
 For general usage instructions, please see the main [Omnipay](https://github.com/thephpleague/omnipay)
 repository.

diff --git a/src/JsonGateway.php b/src/JsonGateway.php
@@ -7,15 +7,25 @@
 /**
  * WorldPay Gateway
  *
- * @link http://www.worldpay.com/support/kb/bg/htmlredirect/rhtml.html
+ * @link https://developer.worldpay.com/jsonapi/docs
  */
 class JsonGateway extends AbstractGateway
 {
+    /**
+     * Name of the gateway
+     *
+     * @return string
+     */
     public function getName()
     {
         return 'WorldPay JSON';
     }
 
+    /**
+     * Setup the default parameters
+     *
+     * @return string[]
+     */
     public function getDefaultParameters()
     {
         return array(
@@ -25,51 +35,109 @@ public function getDefaultParameters()
         );
     }
 
+    /**
+     * Get the stored service key
+     *
+     * @return string
+     */
     public function getServiceKey()
     {
         return $this->getParameter('serviceKey');
     }
 
+    /**
+     * Set the stored service key
+     *
+     * @param string $value  Service key to store
+     */
     public function setServiceKey($value)
     {
         return $this->setParameter('serviceKey', $value);
     }
 
+    /**
+     * Get the stored merchant ID
+     *
+     * @return string
+     */
     public function getMerchantId()
     {
         return $this->getParameter('merchantId');
     }
 
+    /**
+     * Set the stored merchant ID
+     *
+     * @param string $value  Merchant ID to store
+     */
     public function setMerchantId($value)
     {
         return $this->setParameter('merchantId', $value);
     }
 
+    /**
+     * Get the stored client key
+     *
+     * @return string
+     */
     public function getClientKey()
     {
         return $this->getParameter('clientKey');
     }
 
+    /**
+     * Set the stored client key
+     *
+     * @param string $value  Client key to store
+     */
     public function setClientKey($value)
     {
         return $this->setParameter('clientKey', $value);
     }
 
+    /**
+     * Create purchase request
+     *
+     * @param array $parameters
+     *
+     * @return \Omnipay\WorldPay\Message\JsonPurchaseRequest
+     */
     public function purchase(array $parameters = array())
     {
         return $this->createRequest('\Omnipay\WorldPay\Message\JsonPurchaseRequest', $parameters);
     }
 
+    /**
+     * Create authorize request
+     *
+     * @param array $parameters
+     *
+     * @return \Omnipay\WorldPay\Message\JsonAuthorizeRequest
+     */
     public function authorize(array $parameters = array())
     {
         return $this->createRequest('\Omnipay\WorldPay\Message\JsonAuthorizeRequest', $parameters);
     }
 
+    /**
+     * Create refund request
+     *
+     * @param array $parameters
+     *
+     * @return \Omnipay\WorldPay\Message\JsonRefundRequest
+     */
     public function refund(array $parameters = array())
     {
         return $this->createRequest('\Omnipay\WorldPay\Message\JsonRefundRequest', $parameters);
     }
 
+    /**
+     * Create capture request
+     *
+     * @param array $parameters
+     *
+     * @return \Omnipay\WorldPay\Message\JsonCaptureRequest
+     */
     public function capture(array $parameters = array())
     {
         return $this->createRequest('\Omnipay\WorldPay\Message\JsonCaptureRequest', $parameters);

diff --git a/src/Message/JsonAbstractRequest.php b/src/Message/JsonAbstractRequest.php
@@ -2,48 +2,100 @@
 
 namespace Omnipay\WorldPay\Message;
 
+use Guzzle\Http\Message\Response as HttpResponse;
 use Omnipay\Common\Message\AbstractRequest;
 
 abstract class JsonAbstractRequest extends AbstractRequest
 {
+    /**
+     * @var string  API endpoint base to connect to
+     */
     protected $endpoint = 'https://api.worldpay.com/v1';
 
+    /**
+     * Method required to override for getting the specific request endpoint
+     *
+     * @return string
+     */
+    abstract public function getEndpoint();
+
+    /**
+     * The HTTP method used to send data to the API endpoint
+     *
+     * @return string
+     */
     public function getHttpMethod()
     {
         return 'POST';
     }
 
+    /**
+     * Get the stored merchant ID
+     *
+     * @return string
+     */
     public function getMerchantId()
     {
         return $this->getParameter('merchantId');
     }
 
+    /**
+     * Set the stored merchant ID
+     *
+     * @param string $value  Merchant ID to store
+     */
     public function setMerchantId($value)
     {
         return $this->setParameter('merchantId', $value);
     }
 
+    /**
+     * Get the stored service key
+     *
+     * @return string
+     */
     public function getServiceKey()
     {
         return $this->getParameter('serviceKey');
     }
 
+    /**
+     * Set the stored service key
+     *
+     * @param string $value  Service key to store
+     */
     public function setServiceKey($value)
     {
         return $this->setParameter('serviceKey', $value);
     }
 
+    /**
+     * Get the stored client key
+     *
+     * @return string
+     */
     public function getClientKey()
     {
         return $this->getParameter('clientKey');
     }
 
+    /**
+     * Set the stored client key
+     *
+     * @param string $value  Client key to store
+     */
     public function setClientKey($value)
     {
         return $this->setParameter('clientKey', $value);
     }
 
-
+    /**
+     * Make the actual request to WorldPay
+     *
+     * @param mixed $data  The data to encode and send to the API endpoint
+     *
+     * @return HttpResponse  HTTP response object
+     */
     public function sendRequest($data)
     {
         $config = $this->httpClient->getConfig();
@@ -86,7 +138,9 @@ public function getResponseClassName()
     }
 
     /**
-     * @param mixed $data
+     * Send the request to the API then build the response object
+     *
+     * @param mixed $data  The data to encode and send to the API endpoint
      *
      * @return JsonResponse
      */

diff --git a/src/Message/JsonAuthorizeRequest.php b/src/Message/JsonAuthorizeRequest.php
@@ -7,6 +7,11 @@
  */
 class JsonAuthorizeRequest extends JsonPurchaseRequest
 {
+    /**
+     * Set up the authorize-specific data
+     *
+     * @return mixed
+     */
     public function getData()
     {
         $data = parent::getData();

diff --git a/src/Message/JsonAuthorizeResponse.php b/src/Message/JsonAuthorizeResponse.php
@@ -2,29 +2,13 @@
 
 namespace Omnipay\WorldPay\Message;
 
-use Omnipay\Common\Message\AbstractResponse;
-use Omnipay\Common\Message\RequestInterface;
-
 /**
- * WorldPay Purchase Request
+ * WorldPay Authorize Request
  */
-class JsonAuthorizeResponse extends JsonResponse
+class JsonAuthorizeResponse extends JsonPurchaseResponse
 {
-
     /**
-     * Is the response successful?
-     *
-     * @return bool
+     * @var string  Payment status that determines success
      */
-    public function isSuccessful()
-    {
-        $isHttpSuccess = parent::isSuccessful();
-        $isPurchaseSuccess = false;
-
-        if (isset($this->data['paymentStatus']) && $this->data['paymentStatus'] == 'AUTHORIZED') {
-            $isPurchaseSuccess = true;
-        }
-
-        return ($isHttpSuccess && $isPurchaseSuccess);
-    }
+    protected $successfulPaymentStatus = 'AUTHORIZED';
 }
diff --git a/src/Message/JsonPurchaseRequest.php b/src/Message/JsonPurchaseRequest.php
@@ -8,7 +8,9 @@
 class JsonPurchaseRequest extends JsonAbstractRequest
 {
     /**
-     * @return array
+     * Set up the base data for a purchase request
+     *
+     * @return mixed[]
      */
     public function getData()
     {
@@ -74,6 +76,6 @@ public function getEndpoint()
      */
     public function getResponseClassName()
     {
-        return '\Omnipay\WorldPay\Message\JsonResponse';
+        return '\Omnipay\WorldPay\Message\JsonPurchaseResponse';
     }
 }
diff --git a/src/Message/JsonPurchaseResponse.php b/src/Message/JsonPurchaseResponse.php
@@ -2,14 +2,15 @@
 
 namespace Omnipay\WorldPay\Message;
 
-use Omnipay\Common\Message\AbstractResponse;
-use Omnipay\Common\Message\RequestInterface;
-
 /**
  * WorldPay Purchase Request
  */
 class JsonPurchaseResponse extends JsonResponse
 {
+    /**
+     * @var string  Payment status that determines success
+     */
+    protected $successfulPaymentStatus = 'SUCCESS';
 
     /**
      * Is the response successful?
@@ -21,10 +22,36 @@ public function isSuccessful()
         $isHttpSuccess = parent::isSuccessful();
         $isPurchaseSuccess = false;
 
-        if (isset($this->data['paymentStatus']) && $this->data['paymentStatus'] == 'SUCCESS') {
+        if (isset($this->data['paymentStatus']) && $this->data['paymentStatus'] == $this->successfulPaymentStatus) {
             $isPurchaseSuccess = true;
         }
 
         return ($isHttpSuccess && $isPurchaseSuccess);
     }
+
+    /**
+     * What is the relevant description of the transaction response?
+     *
+     * @todo Sometimes the 'description' field is more user-friendly (see simulated eror) - how do we decide which one?
+     *
+     * @return string|null
+     */
+    public function getMessage()
+    {
+        // check for HTTP failure response first
+        $httpMessage = parent::getMessage();
+        if ($httpMessage !== null) {
+            return $httpMessage;
+        }
+
+        // check if descriptive failure reason is available
+        if (!$this->isSuccessful() && isset($this->data['paymentStatusReason'])) {
+            return $this->data['paymentStatusReason'];
+        }
+
+        // check if general payment status is available
+        if (isset($this->data['paymentStatus'])) {
+            return $this->data['paymentStatus'];
+        }
+    }
 }
diff --git a/src/Message/JsonRefundRequest.php b/src/Message/JsonRefundRequest.php
@@ -7,7 +7,11 @@
  */
 class JsonRefundRequest extends JsonAbstractRequest
 {
-
+    /**
+     * Set up the refund-specific data
+     *
+     * @return mixed
+     */
     public function getData()
     {
         $this->validate('amount');