Adding PayPal Digital Goods for Express Checkout Payment Gateway

common/helpers.php

@@ -1,12 +1,19 @@
 <?php
-function phpme_map( $from_array, $map, $return_type = 'Array' ) {
+/**
+ * Substitutes the keys of an array with those of a second array if the
+ * value of the second array matches the key of the first array.
+ * 
+ * @param $from_arary Array arbitrary associated array.
+ * @param $keys Array An array of $key => $value pairs where the $value represents a key to match in the $from_array
+ * @param $return_type String Whether to return the newly created array as an Array (default) or object. 
+ */
+function phpme_map( $from_array, $keys, $return_type = 'Array' ) {
 	$return = array();
-	
-	foreach ( $map as $to_key => $from_key ) {
+
+	foreach ( $keys as $to_key => $from_key )
 		if ( isset( $from_array[$from_key] ) )
-		$return[$to_key] = $from_array[$from_key];
-	}
-
+			$return[$to_key] = $from_array[$from_key];
+
 	if ( $return_type == 'Object' )
 		$return = (Object) $return;
 

gateways/paypal-digital-goods.php

@@ -0,0 +1,79 @@
+<?php
+
+require_once( 'paypal-express-checkout.php' );
+require_once( 'paypal-express-checkout-response.php' );
+
+class PHP_Merchant_Paypal_Digital_Goods extends PHP_Merchant_Paypal_Express_Checkout
+{
+	public function __construct( $options = array() ) {
+		parent::__construct( $options );
+	}
+
+	/**
+	 * Creates and returns the payment component of a PayPal Digital Goods NVP API request.
+	 * 
+	 * PayPal requires the category component for all items in a digital goods purchase to be set as Digital. 
+	 * This function specifies that all goods are digital, then calls @see parent::add_payment() to create
+	 * the rest of the API request (which is the same as a vanilla Express Checkout request).
+	 * 
+	 * @uses parent::add_payment() to create non digital goods components of the request.
+	 * @return Array An array of name value pairs for each element representing a payment in a PayPal Digital Goods NVP API request.
+	 */
+	protected function add_payment( $action ) {
+		$request = parent::add_payment( $action );
+
+		// Make sure PayPal knows all goods are digital
+		for( $i = 0; $i < count( $this->options['items'] ); $i++ )
+			$request += array( "L_PAYMENTREQUEST_0_ITEMCATEGORY{$i}" => 'Digital' );
+
+		return $request;
+	}
+
+	/**
+	 * For Digital Goods purchases, PayPal requires the PAYMENTREQUEST_n_ITEMAMT. This function sets the 'items' flag to required
+	 * then calls @see parent::setup_purchase() to initiate an Express Checkout payment. 
+	 * 
+	 * @uses self::requires() to flag 'items' as required
+	 * @uses parent::setup_purchase() to create and make the request.
+	 * @return PHP_Merchant_Paypal_Express_Checkout_Response An object containing the details of PayPal's response to the request. 
+	 */
+	public function setup_purchase( $options = array() ) {
+		return parent::setup_purchase( $options );
+	}
+
+	/**
+	 * For Digital Goods purchases, PayPal requires the PAYMENTREQUEST_n_ITEMAMT. This function sets the 'items' flag to required
+	 * then calls @see parent::setup_purchase() to complete the payment. 
+	 * 
+	 * @uses self::requires() to flag 'items' as required
+	 * @uses parent::setup_purchase() to create and make the request.
+	 * @return PHP_Merchant_Paypal_Express_Checkout_Response An object containing the details of PayPal's response to the request. 
+	 */
+	public function purchase( $options = array() ) {
+		return parent::purchase( $options );
+	}
+
+
+	/**
+	 * The Javascript to invoke the digital goods in context checkout process.
+	 * 
+	 * No need to call this function manually, required scripts are automatically printed with @see print_buy_buttion(). 
+	 * If you do print this script manually, print it after the button in the DOM to ensure the 
+	 * click event is properly hooked.
+	 */
+	public function get_script( $args = array() ){
+
+		if( empty( $args['element_id'] ) )
+			$args['element_id'] = 'paypal-submit';
+
+		$dg_script  = '<script src ="https://www.paypalobjects.com/js/external/dg.js" type="text/javascript"></script>'
+					. '<script>'
+					. 'var dg = new PAYPAL.apps.DGFlow({'
+					. 'trigger: "' . $args['element_id'] . '"' // the ID of the HTML element which calls setExpressCheckout
+					. '}); </script>';
+
+		return $dg_script;
+	}
+
+
+}

gateways/paypal-express-checkout.php

@@ -8,6 +8,12 @@ public function __construct( $options = array() ) {
 		parent::__construct( $options );
 	}
 
+	/**
+	 * Creates and returns the payment component of a PayPal NVP API request. 
+	 * 
+	 * @param $action String The PayPal Express Checkout payment action. One of Sale, Authorization or Order. For more details, see here: https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_nvp_r_SetExpressCheckout#id1055FM0B05Z__N507DD
+	 * @return Array An array of name value pairs for each element representing a payment in a PayPal NVP API request. 
+	 */
 	protected function add_payment( $action ) {
 		$request = array(
 			'PAYMENTREQUEST_0_AMT'           => $this->format( $this->options['amount'] ),
@@ -61,6 +67,11 @@ protected function add_payment( $action ) {
 		return $request;
 	}
 
+	/**
+	 * Creates and returns the Shipping component of a PayPal NVP API request. 
+	 * 
+	 * @return Array An array of name value pairs for each element required to explain shipping information to PayPal via an NVP API request. 
+	 */
 	protected function add_address() {
 		$map = array(
 			'name'     => 'PAYMENTREQUEST_0_SHIPTONAME',
@@ -83,6 +94,13 @@ protected function add_address() {
 		return $request;
 	}
 
+	/**
+	 * Creates and returns the entire order details component of the PayPal NVP API request string. 
+	 * 
+	 * @uses self::add_address() to add an address to the request
+	 * @uses self::add_payment() to add the payment details to the request
+	 * @return Array An array of name value pairs for each element representing a payment via the PayPal NVP API. 
+	 */
 	protected function build_checkout_request( $action, $options = array() ) {
 		$request = array();
 
@@ -107,6 +125,12 @@ protected function build_checkout_request( $action, $options = array() ) {
 		return $request;
 	}
 
+	/**
+	 * Initiates an Express Checkout payment by calling PayPal to perform the SetExpressCheckout NVP API method. 
+	 * 
+	 * @uses self::build_checkout_request() to create the request
+	 * @return PHP_Merchant_Paypal_Express_Checkout_Response An object containing the details of PayPal's response to the request. 
+	 */
 	public function setup_purchase( $options = array() ) {
 		$this->options = array_merge( $this->options, $options );
 		$this->requires( 'amount', 'return_url', 'cancel_url' );
@@ -116,18 +140,35 @@ public function setup_purchase( $options = array() ) {
 		return new PHP_Merchant_Paypal_Express_Checkout_Response( $response_str );
 	}
 
+	/**
+	 * Creates and returns all the name => value pairs required to get checkout details from PayPal, which is just the token for the checkout. 
+	 * 
+	 * @return Array An array of name value pairs for each element required to perform a GetExpressCheckoutDetails NVP API request
+	 */
 	public function build_get_details_request( $token ) {
 		return array(
 			'TOKEN' => $token,
 		);
 	}
 
+	/**
+	 * Gets the details of an express checkout transaction by calling PayPal to perform the GetExpressCheckoutDetails NVP API method. 
+	 * 
+	 * @uses self::build_get_details_request() to create the request
+	 * @return PHP_Merchant_Paypal_Express_Checkout_Response An object containing the details of PayPal's response to the request. 
+	 */
 	public function get_details_for( $token ) {
 		$request = $this->build_get_details_request( $token );
 		$response_str = $this->commit( 'GetExpressCheckoutDetails', $request );
 		return new PHP_Merchant_Paypal_Express_Checkout_Response( $response_str );
 	}
 
+	/**
+	 * Completes an Express Checkout transaction by calling PayPal to perform the DoExpressCheckoutPayment NVP API method. 
+	 * 
+	 * @uses self::build_checkout_request() to create the request
+	 * @return PHP_Merchant_Paypal_Express_Checkout_Response An object containing the details of PayPal's response to the request. 
+	 */
 	public function purchase( $options = array() ) {
 		$this->options = array_merge( $this->options, $options );
 		$this->requires( 'amount', 'token', 'payer_id' );