Merge pull request #9 from delatbabel/add-docblocks-1

Add docblocks

src/ConvergeGateway.php

@@ -1,11 +1,108 @@
-<?php namespace Omnipay\Elavon;
+<?php
+
+namespace Omnipay\Elavon;
 
 use Omnipay\Common\AbstractGateway;
 
 /**
  * Elavon's Converge Gateway
  *
+ * This class processes form post requests using the Elavon/Converge gateway as documented here:
+ * https://resourcecentre.elavonpaymentgateway.com/index.php/download-developer-guide
+ *
+ * Also here: https://www.convergepay.com/converge-webapp/developer/#/welcome
+ *
+ * ### Test Mode
+ *
+ * In order to begin testing you will need the following parameters from Elavon/Converge:
+ *
+ * * merchantId, aka ssl_merchant_id
+ * * username, aka ssl_user_id
+ * * password, aka ssl_pin
+ *
+ * These parameters are issued for a short time only.  You need to contact Converge to request an extension
+ * a few days before these parameters expire.
+ *
+ * ### Example
+ *
+ * #### Initialize Gateway
+ *
+ * <code>
+ * //
+ * // Put your gateway credentials here.
+ * //
+ * $credentials = array(
+ *     'merchantId'        => '000000',
+ *     'username'          => 'USERNAME',
+ *     'password'          => 'PASSWORD'
+ *     'testMode'          => true,            // Or false if you want to test production mode
+ * );
+ *
+ * // Create a gateway object
+ * // (routes to GatewayFactory::create)
+ * $gateway = Omnipay::create('Elavon_Converge');
+ *
+ * // Initialise the gateway
+ * $gateway->initialize($credentials);
+ * </code>
+ *
+ * #### Direct Credit Card Payment
+ *
+ * <code>
+ * // Create a credit card object
+ * // The card number doesn't appear to matter in test mode.
+ * $card = new CreditCard(array(
+ *     'firstName'             => 'Example',
+ *     'lastName'              => 'Customer',
+ *     'number'                => '4444333322221111',
+ *     'expiryMonth'           => '01',
+ *     'expiryYear'            => '2020',
+ *     'cvv'                   => '123',
+ *     'billingAddress1'       => '1 Scrubby Creek Road',
+ *     'billingCountry'        => 'AU',
+ *     'billingCity'           => 'Scrubby Creek',
+ *     'billingPostcode'       => '4999',
+ *     'billingState'          => 'QLD',
+ * ));
+ *
+ * // Do a purchase transaction on the gateway
+ * try {
+ *     $transaction = $gateway->purchase(array(
+ *         'amount'        => '10.00',
+ *         'currency'      => 'USD',
+ *         'description'   => 'This is a test purchase transaction.',
+ *         'card'          => $card,
+ *     ));
+ *     $response = $transaction->send();
+ *     $data = $response->getData();
+ *     echo "Gateway purchase response data == " . print_r($data, true) . "\n";
+ *
+ *     if ($response->isSuccessful()) {
+ *         echo "Purchase transaction was successful!\n";
+ *     }
+ * } catch (\Exception $e) {
+ *     echo "Exception caught while attempting authorize.\n";
+ *     echo "Exception type == " . get_class($e) . "\n";
+ *     echo "Message == " . $e->getMessage() . "\n";
+ * }
+ * </code>
+ *
+ * ### Dashboard
+ *
+ * For test payments you should be given a Login URL which will be
+ * https://demo.myvirtualmerchant.com/VirtualMerchantDemo/login.do
+ *
+ * ... and some website credentials.  These will be:
+ *
+ * * Account ID
+ * * User ID
+ * * Password
+ *
+ * The password usually needs to be reset periodically.
+ *
  * @link https://www.myvirtualmerchant.com/VirtualMerchant/
+ * @link https://resourcecentre.elavonpaymentgateway.com/index.php/download-developer-guide
+ * @see \Omnipay\Elavon\Message\ConvergeAbstractRequest
  */
 class ConvergeGateway extends AbstractGateway
 {
@@ -23,39 +120,72 @@ public function getDefaultParameters()
         );
     }
 
+    /**
+     * Get the merchant ID
+     *
+     * @return string
+     */
     public function getMerchantId()
     {
         return $this->getParameter('merchantId');
     }
 
+    /**
+     * Set the merchant ID
+     *
+     * @param string $value
+     * @return ConvergeGateway provides a fluent interface
+     */
     public function setMerchantId($value)
     {
         return $this->setParameter('merchantId', $value);
     }
 
+    /**
+     * Get the username
+     *
+     * @return string
+     */
     public function getUsername()
     {
         return $this->getParameter('username');
     }
 
+    /**
+     * Set the username
+     *
+     * @param string $value
+     * @return ConvergeGateway provides a fluent interface
+     */
     public function setUsername($value)
     {
         return $this->setParameter('username', $value);
     }
 
+    /**
+     * Get the password
+     *
+     * @return string
+     */
     public function getPassword()
     {
         return $this->getParameter('password');
     }
 
+    /**
+     * Set the password
+     *
+     * @param string $value
+     * @return ConvergeGateway provides a fluent interface
+     */
     public function setPassword($value)
     {
         return $this->setParameter('password', $value);
     }
 
     /**
      * @param array $parameters
-     * @return \Omnipay\Elavon\Message\AuthorizeRequest
+     * @return \Omnipay\Elavon\Message\ConvergeAuthorizeRequest
      */
     public function authorize(array $parameters = array())
     {
@@ -64,7 +194,7 @@ public function authorize(array $parameters = array())
 
     /**
      * @param array $parameters
-     * @return \Omnipay\Elavon\Message\PurchaseRequest
+     * @return \Omnipay\Elavon\Message\ConvergePurchaseRequest
      */
     public function purchase(array $parameters = array())
     {
@@ -73,7 +203,7 @@ public function purchase(array $parameters = array())
 
     /**
      * @param array $parameters
-     * @return \Omnipay\Elavon\Message\PurchaseRequest
+     * @return \Omnipay\Elavon\Message\ConvergePurchaseRequest
      */
     public function createCard(array $parameters = array())
     {