Updated Invoicing APIs

- Updated Model objects.
- Updated Samples.
- Updated Tests.

lib/PayPal/Api/Address.php

@@ -17,7 +17,7 @@ class Address extends BaseAddress
      * Phone number in E.123 format.
      *
      * @param string $phone
-     *
+     * 
      * @return $this
      */
     public function setPhone($phone)

lib/PayPal/Api/BillingInfo.php

@@ -24,7 +24,7 @@
 class BillingInfo extends PayPalModel
 {
     /**
-     * Email address of the invoice recipient. 260 characters max.
+     * The invoice recipient email address. Maximum length is 260 characters.
      *
      * @param string $email
      * 
@@ -37,7 +37,7 @@ public function setEmail($email)
     }
 
     /**
-     * Email address of the invoice recipient. 260 characters max.
+     * The invoice recipient email address. Maximum length is 260 characters.
      *
      * @return string
      */
@@ -47,7 +47,7 @@ public function getEmail()
     }
 
     /**
-     * First name of the invoice recipient. 30 characters max.
+     * The invoice recipient first name. Maximum length is 30 characters.
      *
      * @param string $first_name
      * 
@@ -60,7 +60,7 @@ public function setFirstName($first_name)
     }
 
     /**
-     * First name of the invoice recipient. 30 characters max.
+     * The invoice recipient first name. Maximum length is 30 characters.
      *
      * @return string
      */
@@ -70,7 +70,7 @@ public function getFirstName()
     }
 
     /**
-     * Last name of the invoice recipient. 30 characters max.
+     * The invoice recipient last name. Maximum length is 30 characters.
      *
      * @param string $last_name
      * 
@@ -83,7 +83,7 @@ public function setLastName($last_name)
     }
 
     /**
-     * Last name of the invoice recipient. 30 characters max.
+     * The invoice recipient last name. Maximum length is 30 characters.
      *
      * @return string
      */
@@ -93,7 +93,7 @@ public function getLastName()
     }
 
     /**
-     * Company business name of the invoice recipient. 100 characters max.
+     * The invoice recipient company business name. Maximum length is 100 characters.
      *
      * @param string $business_name
      * 
@@ -106,7 +106,7 @@ public function setBusinessName($business_name)
     }
 
     /**
-     * Company business name of the invoice recipient. 100 characters max.
+     * The invoice recipient company business name. Maximum length is 100 characters.
      *
      * @return string
      */
@@ -116,7 +116,7 @@ public function getBusinessName()
     }
 
     /**
-     * Address of the invoice recipient.
+     * The invoice recipient address.
      *
      * @param \PayPal\Api\InvoiceAddress $address
      * 
@@ -129,7 +129,7 @@ public function setAddress($address)
     }
 
     /**
-     * Address of the invoice recipient.
+     * The invoice recipient address.
      *
      * @return \PayPal\Api\InvoiceAddress
      */
@@ -139,8 +139,8 @@ public function getAddress()
     }
 
     /**
-     * Language of the email sent to the payer. Will only be used if payer doesn't have a PayPal account.
-     * Valid Values: ["da_DK", "de_DE", "en_AU", "en_GB", "en_US", "es_ES", "es_XC", "fr_CA", "fr_FR", "fr_XC", "he_IL", "id_ID", "it_IT", "ja_JP", "nl_NL", "no_NO", "pl_PL", "pt_BR", "pt_PT", "ru_RU", "sv_SE", "th_TH", "tr_TR", "zh_CN", "zh_HK", "zh_TW", "zh_XC"]
+     * The language in which the email was sent to the payer. Used only when the payer does not have a PayPal account.
+     * Valid Values: ["da_DK", "de_DE", "en_AU", "en_GB", "en_US", "es_ES", "es_XC", "fr_CA", "fr_FR", "fr_XC", "he_IL", "id_ID", "it_IT", "ja_JP", "nl_NL", "no_NO", "pl_PL", "pt_BR", "pt_PT", "ru_RU", "sv_SE", "th_TH", "zh_CN", "zh_HK", "zh_TW", "zh_XC"]
      *
      * @param string $language
      * 
@@ -153,7 +153,7 @@ public function setLanguage($language)
     }
 
     /**
-     * Language of the email sent to the payer. Will only be used if payer doesn't have a PayPal account.
+     * The language in which the email was sent to the payer. Used only when the payer does not have a PayPal account.
      *
      * @return string
      */
@@ -163,7 +163,7 @@ public function getLanguage()
     }
 
     /**
-     * Option to display additional information such as business hours. 40 characters max.
+     * Additional information, such as business hours. Maximum length is 40 characters.
      *
      * @param string $additional_info
      * 
@@ -176,7 +176,7 @@ public function setAdditionalInfo($additional_info)
     }
 
     /**
-     * Option to display additional information such as business hours. 40 characters max.
+     * Additional information, such as business hours. Maximum length is 40 characters.
      *
      * @return string
      */

lib/PayPal/Api/CancelNotification.php

@@ -15,6 +15,7 @@
  * @property string note
  * @property bool send_to_merchant
  * @property bool send_to_payer
+ * @property string[] cc_emails
  */
 class CancelNotification extends PayPalModel
 {
@@ -65,7 +66,7 @@ public function getNote()
     }
 
     /**
-     * A flag indicating whether a copy of the email has to be sent to the merchant.
+     * Indicates whether to send a copy of the notification to the merchant.
      *
      * @param bool $send_to_merchant
      * 
@@ -78,7 +79,7 @@ public function setSendToMerchant($send_to_merchant)
     }
 
     /**
-     * A flag indicating whether a copy of the email has to be sent to the merchant.
+     * Indicates whether to send a copy of the notification to the merchant.
      *
      * @return bool
      */
@@ -88,7 +89,7 @@ public function getSendToMerchant()
     }
 
     /**
-     * A flag indicating whether a copy of the email has to be sent to the payer.
+     * Indicates whether to send a copy of the notification to the payer.
      *
      * @param bool $send_to_payer
      * 
@@ -101,7 +102,7 @@ public function setSendToPayer($send_to_payer)
     }
 
     /**
-     * A flag indicating whether a copy of the email has to be sent to the payer.
+     * Indicates whether to send a copy of the notification to the payer.
      *
      * @return bool
      */
@@ -110,4 +111,57 @@ public function getSendToPayer()
         return $this->send_to_payer;
     }
 
+    /**
+     * Applicable for invoices created with Cc emails. If this field is not in the body, all the cc email addresses added as part of the invoice shall be notified else this field can be used to limit the list of email addresses. Note: additional email addresses are not supported.
+     *
+     * @param string[] $cc_emails
+     * 
+     * @return $this
+     */
+    public function setCcEmails($cc_emails)
+    {
+        $this->cc_emails = $cc_emails;
+        return $this;
+    }
+
+    /**
+     * Applicable for invoices created with Cc emails. If this field is not in the body, all the cc email addresses added as part of the invoice shall be notified else this field can be used to limit the list of email addresses. Note: additional email addresses are not supported.
+     *
+     * @return string[]
+     */
+    public function getCcEmails()
+    {
+        return $this->cc_emails;
+    }
+
+    /**
+     * Append CcEmails to the list.
+     *
+     * @param string $string
+     * @return $this
+     */
+    public function addCcEmail($string)
+    {
+        if (!$this->getCcEmails()) {
+            return $this->setCcEmails(array($string));
+        } else {
+            return $this->setCcEmails(
+                array_merge($this->getCcEmails(), array($string))
+            );
+        }
+    }
+
+    /**
+     * Remove CcEmails from the list.
+     *
+     * @param string $string
+     * @return $this
+     */
+    public function removeCcEmail($string)
+    {
+        return $this->setCcEmails(
+            array_diff($this->getCcEmails(), array($string))
+        );
+    }
+
 }

lib/PayPal/Api/Cost.php

@@ -9,7 +9,7 @@
 /**
  * Class Cost
  *
- * Cost as a percent. For example, 10% should be entered as 10. Alternatively, cost as an amount. For example, an amount of 5 should be entered as 5.
+ * Cost as a percent or an amount. For example, to specify 10%, enter `10`. Alternatively, to specify an amount of 5, enter `5`.
  *
  * @package PayPal\Api
  *
@@ -44,7 +44,7 @@ public function getPercent()
     }
 
     /**
-     * Cost in amount. Range of 0 to 999999.99.
+     * The cost, as an amount. Valid range is from 0 to 1,000,000.
      *
      * @param \PayPal\Api\Currency $amount
      * 
@@ -57,7 +57,7 @@ public function setAmount($amount)
     }
 
     /**
-     * Cost in amount. Range of 0 to 999999.99.
+     * The cost, as an amount. Valid range is from 0 to 1,000,000.
      *
      * @return \PayPal\Api\Currency
      */

lib/PayPal/Api/CustomAmount.php

@@ -7,7 +7,7 @@
 /**
  * Class CustomAmount
  *
- * Custom amount applied on an invoice. If a label is included then the amount cannot be empty.
+ * The custom amount applied on an invoice. If you include a label, the amount cannot be empty.
  *
  * @package PayPal\Api
  *
@@ -17,7 +17,7 @@
 class CustomAmount extends PayPalModel
 {
     /**
-     * Custom amount label. 25 characters max.
+     * The custom amount label. Maximum length is 25 characters.
      *
      * @param string $label
      * 
@@ -30,7 +30,7 @@ public function setLabel($label)
     }
 
     /**
-     * Custom amount label. 25 characters max.
+     * The custom amount label. Maximum length is 25 characters.
      *
      * @return string
      */
@@ -40,7 +40,7 @@ public function getLabel()
     }
 
     /**
-     * Custom amount value. Range of 0 to 999999.99.
+     * The custom amount value. Valid range is from -999999.99 to 999999.99.
      *
      * @param \PayPal\Api\Currency $amount
      * 
@@ -53,7 +53,7 @@ public function setAmount($amount)
     }
 
     /**
-     * Custom amount value. Range of 0 to 999999.99.
+     * The custom amount value. Valid range is from -999999.99 to 999999.99.
      *
      * @return \PayPal\Api\Currency
      */

lib/PayPal/Api/ErrorDetails.php

@@ -20,7 +20,7 @@ class ErrorDetails extends PayPalModel
      * Name of the field that caused the error.
      *
      * @param string $field
-     *
+     * 
      * @return $this
      */
     public function setField($field)
@@ -43,7 +43,7 @@ public function getField()
      * Reason for the error.
      *
      * @param string $issue
-     *
+     * 
      * @return $this
      */
     public function setIssue($issue)

lib/PayPal/Api/FileAttachment.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace PayPal\Api;
+
+use PayPal\Common\PayPalModel;
+use PayPal\Validation\UrlValidator;
+
+/**
+ * Class FileAttachment
+ *
+ * File attached to an invoice or template
+ *
+ * @package PayPal\Api
+ *
+ * @property string name
+ * @property string url
+ */
+class FileAttachment extends PayPalModel
+{
+    /**
+     * Name of the file attached.
+     *
+     * @param string $name
+     * 
+     * @return $this
+     */
+    public function setName($name)
+    {
+        $this->name = $name;
+        return $this;
+    }
+
+    /**
+     * Name of the file attached.
+     *
+     * @return string
+     */
+    public function getName()
+    {
+        return $this->name;
+    }
+
+    /**
+     * URL of the attached file that can be downloaded.
+     *
+     * @param string $url
+     * @throws \InvalidArgumentException
+     * @return $this
+     */
+    public function setUrl($url)
+    {
+        UrlValidator::validate($url, "Url");
+        $this->url = $url;
+        return $this;
+    }
+
+    /**
+     * URL of the attached file that can be downloaded.
+     *
+     * @return string
+     */
+    public function getUrl()
+    {
+        return $this->url;
+    }
+
+}