Merge pull request #8 from delatbabel/update-docblocks

Add docblocks, deprecate inquiry for fetchTransaction

.gitignore

@@ -2,3 +2,9 @@
 composer.lock
 composer.phar
 phpunit.xml
+.directory
+.idea/
+dirlist.app
+dirlist.vendor
+dirlist.cache
+/documents/

README.md

@@ -7,7 +7,7 @@
 [![Total Downloads](https://poser.pugx.org/omnipay/payflow/d/total.png)](https://packagist.org/packages/omnipay/payflow)
 
 [Omnipay](https://github.com/thephpleague/omnipay) is a framework agnostic, multi-gateway payment
-processing library for PHP 5.3+. This package implements Payflow support for Omnipay.
+processing library for PHP 5.3+. This package implements [Payflow](https://developer.paypal.com/docs/classic/products/payflow-gateway/) support for Omnipay.
 
 ## Installation
 
@@ -31,7 +31,7 @@ And run composer to update your dependencies:
 
 The following gateways are provided by this package:
 
-* Payflow_Pro
+* [Payflow_Pro](https://developer.paypal.com/docs/classic/products/payflow-gateway/)
 
 For general usage instructions, please see the main [Omnipay](https://github.com/thephpleague/omnipay)
 repository.

makedoc.sh

@@ -0,0 +1,157 @@
+#!/bin/sh
+
+#
+# Smart little documentation generator.
+# GPL/LGPL
+# (c) Del 2015 http://www.babel.com.au/
+#
+
+APPNAME='Omnipay Payflow Gateway Documentation'
+CMDFILE=apigen.cmd.$$
+DESTDIR=./documents
+SRCDIRS="src"
+VENDORDIRS="vendor/guzzle vendor/omnipay"
+
+#
+# Ensure that dependencies are installed (including codeception and phpunit)
+#
+if [ -f composer.lock ]; then
+    /usr/local/bin/composer install
+else
+    /usr/local/bin/composer update
+fi
+
+#
+# Find apigen, either in the path or as a local phar file
+#
+if [ -f apigen.phar ]; then
+    APIGEN="php apigen.phar"
+
+else
+    APIGEN=`which apigen`
+    if [ ! -f "$APIGEN" ]; then
+
+        # Search for phpdoc if apigen is not found.
+        if [ -f phpDocumentor.phar ]; then
+            PHPDOC="php phpDocumentor.phar"
+
+        else
+            PHPDOC=`which phpdoc`
+            if [ ! -f "$PHPDOC" ]; then
+                echo "Neither apigen nor phpdoc is installed in the path or locally, please install one of them"
+                echo "see http://www.apigen.org/ or http://www.phpdoc.org/"
+                exit 1
+            fi
+        fi
+    fi
+fi
+
+#
+# As of version 4 of apigen need to use the generate subcommand
+#
+if [ ! -z "$APIGEN" ]; then
+    APIGEN="$APIGEN generate"
+fi
+
+#
+# Without any arguments this builds the entire system documentation,
+# making the cache file first if required.
+#
+if [ -z "$1" ]; then
+    #
+    # Check to see that the cache has been made.
+    #
+    if [ ! -f dirlist.cache ]; then
+        echo "Making dirlist.cache file"
+        $0 makecache
+    fi
+
+    #
+    # Build the apigen/phpdoc command in a file.
+    #
+    if [ ! -z "$APIGEN" ]; then
+        echo "$APIGEN --php --tree --title '$APPNAME API Documentation' --destination $DESTDIR/main \\" > $CMDFILE
+        cat dirlist.cache | while read dir; do
+            echo "--source $dir \\" >> $CMDFILE
+        done
+        echo "" >> $CMDFILE
+
+    elif [ ! -z "$PHPDOC" ]; then
+        echo "$PHPDOC --sourcecode --title '$APPNAME API Documentation' --target $DESTDIR/main --directory \\" > $CMDFILE
+        cat dirlist.cache | while read dir; do
+            echo "${dir},\\" >> $CMDFILE
+        done
+        echo "" >> $CMDFILE
+
+    else
+        "Neither apigen nor phpdoc are found, how did I get here?"
+        exit 1
+    fi
+
+    #
+    # Run the apigen command
+    #
+    rm -rf $DESTDIR/main
+    mkdir -p $DESTDIR/main
+    . ./$CMDFILE
+
+    /bin/rm -f ./$CMDFILE
+
+#
+# The "makecache" argument causes the script to just make the cache file
+#
+elif [ "$1" = "makecache" ]; then
+    echo "Find application source directories"
+    find $SRCDIRS -name \*.php -print | \
+        (
+            while read file; do
+                grep -q 'class' $file && dirname $file
+            done
+        ) | sort -u | \
+        grep -v -E 'config|docs|migrations|test|Test|views|web' > dirlist.app
+
+    echo "Find vendor source directories"
+    find $VENDORDIRS -name \*.php -print | \
+        (
+            while read file; do
+                grep -q 'class' $file && dirname $file
+            done
+        ) | sort -u | \
+        grep -v -E 'config|docs|migrations|test|Test|views|codesniffer|phpmd|pdepend|php-parser|codeception|phpunit' > dirlist.vendor
+
+    #
+    # Filter out any directories for which apigen fails
+    #
+    echo "Filter source directories"
+    mkdir -p $DESTDIR/tmp
+    cat dirlist.app dirlist.vendor | while read dir; do
+        if [ ! -z "$APIGEN" ]; then
+            $APIGEN --quiet --title "Test please ignore" \
+                --source $dir \
+                --destination $DESTDIR/tmp && (
+                    echo "Including $dir"
+                    echo $dir >> dirlist.cache
+                ) || (
+                    echo "Excluding $dir"
+                )
+
+        elif [ ! -z "$PHPDOC" ]; then
+            $PHPDOC --quiet --title "Test please ignore" \
+                --directory $dir \
+                --target $DESTDIR/tmp && (
+                    echo "Including $dir"
+                    echo $dir >> dirlist.cache
+                ) || (
+                    echo "Excluding $dir"
+                )
+
+        fi
+    done
+    echo "Documentation cache dirlist.cache built OK"
+
+    #
+    # Clean up
+    #
+    /bin/rm -rf $DESTDIR/tmp
+
+fi

runtests.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+
+#
+# Command line runner for unit tests for composer projects
+# (c) Del 2015 http://www.babel.com.au/
+# No Rights Reserved
+#
+
+#
+# Clean up after any previous test runs
+#
+mkdir -p documents
+rm -rf documents/coverage-html-new
+rm -f documents/coverage.xml
+
+#
+# Run phpunit
+#
+vendor/bin/phpunit --coverage-html documents/coverage-html-new --coverage-clover documents/coverage.xml
+
+if [ -d documents/coverage-html-new ]; then
+  rm -rf documents/coverage-html
+  mv documents/coverage-html-new documents/coverage-html
+fi
+

src/Message/AuthorizeRequest.php

@@ -6,48 +6,153 @@
 
 /**
  * Payflow Authorize Request
+ *
+ * ### Example
+ *
+ * <code>
+ * // Create a gateway for the Payflow pro Gateway
+ * // (routes to GatewayFactory::create)
+ * $gateway = Omnipay::create('Payflow_Pro');
+ *
+ * // Initialise the gateway
+ * $gateway->initialize(array(
+ *     'username'       => $myusername,
+ *     'password'       => $mypassword,
+ *     'vendor'         => $mymerchantid,
+ *     'partner'        => $PayPalPartner,
+ *     'testMode'       => true, // Or false for live transactions.
+ * ));
+ *
+ * // Create a credit card object
+ * // This card can be used for testing.
+ * $card = new CreditCard(array(
+ *             'firstName'    => 'Example',
+ *             'lastName'     => 'Customer',
+ *             'number'       => '4242424242424242',
+ *             'expiryMonth'  => '01',
+ *             'expiryYear'   => '2020',
+ *             'cvv'          => '123',
+ * ));
+ *
+ * // Do an authorize transaction on the gateway
+ * $transaction = $gateway->authorize(array(
+ *     'amount'                   => '10.00',
+ *     'currency'                 => 'AUD',
+ *     'card'                     => $card,
+ * ));
+ * $response = $transaction->send();
+ * if ($response->isSuccessful()) {
+ *     echo "Authorize transaction was successful!\n";
+ *     $sale_id = $response->getTransactionReference();
+ *     echo "Transaction reference = " . $sale_id . "\n";
+ * }
+ * </code>
  */
 class AuthorizeRequest extends AbstractRequest
 {
     protected $liveEndpoint = 'https://payflowpro.paypal.com';
     protected $testEndpoint = 'https://pilot-payflowpro.paypal.com';
     protected $action = 'A';
 
+    /**
+     * Get the username.
+     *
+     * This is the ID that you specified when you got the Payflow account.
+     *
+     * @return string
+     */
     public function getUsername()
     {
         return $this->getParameter('username');
     }
 
+    /**
+     * Set the username.
+     *
+     * This is the ID that you specified when you got the Payflow account.
+     *
+     * @param string $value
+     * @return AuthorizeRequest provides a fluent interface.
+     */
     public function setUsername($value)
     {
         return $this->setParameter('username', $value);
     }
 
+    /**
+     * Get the password.
+     *
+     * This is the password that you specified when you got the Payflow account.
+     *
+     * @return string
+     */
     public function getPassword()
     {
         return $this->getParameter('password');
     }
 
+    /**
+     * Set the password.
+     *
+     * This is the password that you specified when you got the Payflow account.
+     *
+     * @param string $value
+     * @return AuthorizeRequest provides a fluent interface.
+     */
     public function setPassword($value)
     {
         return $this->setParameter('password', $value);
     }
 
+    /**
+     * Get the vendor.
+     *
+     * The ID that you specified when you got the Payflow account, the same as the username unless you
+     * have created additional users on the account. That is, the merchant login ID for the account.
+     *
+     * @return string
+     */
     public function getVendor()
     {
         return $this->getParameter('vendor');
     }
 
+    /**
+     * Set the vendor.
+     *
+     * The ID that you specified when you got the Payflow account, the same as the username unless you
+     * have created additional users on the account. That is, the merchant login ID for the account.
+     *
+     * @param string $value
+     * @return AuthorizeRequest provides a fluent interface.
+     */
     public function setVendor($value)
     {
         return $this->setParameter('vendor', $value);
     }
 
+    /**
+     * Get the partner.
+     *
+     * The Payflow partner. This may be PayPal, or if an account was provided by an authorized PayPal
+     * reseller, who registered a Payflow user, then the ID provided by the reseller is used.
+     *
+     * @return string
+     */
     public function getPartner()
     {
         return $this->getParameter('partner');
     }
 
+    /**
+     * Set the partner.
+     *
+     * The Payflow partner. This may be PayPal, or if an account was provided by an authorized PayPal
+     * reseller, who registered a Payflow user, then the ID provided by the reseller is used.
+     *
+     * @param string $value
+     * @return AuthorizeRequest provides a fluent interface.
+     */
     public function setPartner($value)
     {
         return $this->setParameter('partner', $value);
@@ -73,11 +178,17 @@ public function setComment2($value)
         return $this->setParameter('comment2', $value);
     }
 
+    /**
+     * @deprecated
+     */
     public function getOrigid()
     {
         return $this->getParameter('origid');
     }
 
+    /**
+     * @deprecated
+     */
     public function setOrigid($value)
     {
         return $this->setParameter('origid', $value);
@@ -117,7 +228,7 @@ public function getData()
             $data['BILLTOZIP'] = $this->getCard()->getPostcode();
             $data['BILLTOCOUNTRY'] = $this->getCard()->getCountry();
         }
-        
+
         $data['TENDER'] = 'C';
         $data['AMT'] = $this->getAmount();
         $data['COMMENT1'] = $this->getDescription();