MAGETWO-33664: Refactor Sales module to use mutable data object interfaces

 - relax setter parameters when getters handle more than an array of objects

Author: Mike Weis

app/code/Magento/Sales/Api/Data/CreditmemoInterface.php

@@ -561,13 +561,29 @@ public function getUpdatedAt();
      */
     public function getItems();
 
+    /**
+     * Sets credit memo items.
+     *
+     * @param \Magento\Sales\Api\Data\CreditmemoItemInterface[] $items
+     * @return $this
+     */
+    public function setItems($items);
+
     /**
      * Gets credit memo comments.
      *
      * @return \Magento\Sales\Api\Data\CreditmemoCommentInterface[]|null Array of any credit memo comments. Otherwise, null.
      */
     public function getComments();
 
+    /**
+     * Sets credit memo comments.
+     *
+     * @param \Magento\Sales\Api\Data\CreditmemoCommentInterface[] $comments
+     * @return $this
+     */
+    public function setComments($comments);
+
     /**
      * Sets the credit memo store ID.
      *
@@ -911,20 +927,4 @@ public function setBaseShippingInclTax($amount);
      * @return $this
      */
     public function setDiscountDescription($description);
-
-    /**
-     * Sets credit memo items.
-     *
-     * @param \Magento\Sales\Api\Data\CreditmemoItemInterface[] $items
-     * @return $this
-     */
-    public function setItems(array $items = null);
-
-    /**
-     * Sets credit memo comments.
-     *
-     * @param \Magento\Sales\Api\Data\CreditmemoCommentInterface[] $comments
-     * @return $this
-     */
-    public function setComments(array $comments = null);
 }

app/code/Magento/Sales/Api/Data/InvoiceInterface.php

@@ -515,13 +515,29 @@ public function getUpdatedAt();
      */
     public function getItems();
 
+    /**
+     * Sets the items in the invoice.
+     *
+     * @param \Magento\Sales\Api\Data\InvoiceItemInterface[] $items
+     * @return $this
+     */
+    public function setItems($items);
+
     /**
      * Gets the comments, if any, for the invoice.
      *
      * @return \Magento\Sales\Api\Data\InvoiceCommentInterface[]|null Array of any invoice comments. Otherwise, null.
      */
     public function getComments();
 
+    /**
+     * Sets the comments, if any, for the invoice.
+     *
+     * @param \Magento\Sales\Api\Data\InvoiceCommentInterface[] $comments
+     * @return $this
+     */
+    public function setComments($comments);
+
     /**
      * Sets the updated-at timestamp for the invoice.
      *
@@ -849,20 +865,4 @@ public function setBaseTotalRefunded($amount);
      * @return $this
      */
     public function setDiscountDescription($description);
-
-    /**
-     * Sets the items in the invoice.
-     *
-     * @param \Magento\Sales\Api\Data\InvoiceItemInterface[] $items
-     * @return $this
-     */
-    public function setItems($items);
-
-    /**
-     * Sets the comments, if any, for the invoice.
-     *
-     * @param \Magento\Sales\Api\Data\InvoiceCommentInterface[] $comments
-     * @return $this
-     */
-    public function setComments(array $comments = null);
 }

app/code/Magento/Sales/Api/Data/OrderInterface.php

@@ -1526,41 +1526,89 @@ public function getXForwardedFor();
      */
     public function getItems();
 
+    /**
+     * Sets items for the order.
+     *
+     * @param \Magento\Sales\Api\Data\OrderItemInterface[] $items
+     * @return $this
+     */
+    public function setItems($items);
+
     /**
      * Gets the billing address, if any, for the order.
      *
      * @return \Magento\Sales\Api\Data\OrderAddressInterface|null Billing address. Otherwise, null.
      */
     public function getBillingAddress();
 
+    /**
+     * Sets the billing address, if any, for the order.
+     *
+     * @param \Magento\Sales\Api\Data\OrderAddressInterface $billingAddress
+     * @return $this
+     */
+    public function setBillingAddress(\Magento\Sales\Api\Data\OrderAddressInterface $billingAddress = null);
+
     /**
      * Gets the shipping address, if any, for the order.
      *
      * @return \Magento\Sales\Api\Data\OrderAddressInterface|null Shipping address. Otherwise, null.
      */
     public function getShippingAddress();
 
+    /**
+     * Sets the shipping address, if any, for the order.
+     *
+     * @param \Magento\Sales\Api\Data\OrderAddressInterface $shippingAddress
+     * @return $this
+     */
+    public function setShippingAddress(\Magento\Sales\Api\Data\OrderAddressInterface $shippingAddress = null);
+
     /**
      * Gets the payments for the order.
      *
      * @return \Magento\Sales\Api\Data\OrderPaymentInterface[] Array of payments.
      */
     public function getPayments();
 
+    /**
+     * Sets the payments for the order.
+     *
+     * @param \Magento\Sales\Api\Data\OrderPaymentInterface[] $payments
+     * @return $this
+     */
+    public function setPayments(array $payments = null);
+
     /**
      * Gets addresses for the order.
      *
      * @return \Magento\Sales\Api\Data\OrderAddressInterface[] Array of addresses.
      */
     public function getAddresses();
 
+    /**
+     * Sets addresses for the order.
+     *
+     * @param \Magento\Sales\Api\Data\OrderAddressInterface[] $addresses
+     * @return $this
+     */
+    public function setAddresses(array $addresses = null);
+
     /**
      * Gets status histories for the order.
      *
      * @return \Magento\Sales\Api\Data\OrderStatusHistoryInterface[] Array of status histories.
      */
     public function getStatusHistories();
 
+    /**
+     * Sets status histories for the order.
+     *
+     * @param \Magento\Sales\Api\Data\OrderStatusHistoryInterface[] $statusHistories
+     * @return $this
+     */
+    public function setStatusHistories(array $statusHistories = null);
+
     /**
      * Sets the state for the order.
      *
@@ -2616,52 +2664,4 @@ public function setShippingInclTax($amount);
      * @return $this
      */
     public function setBaseShippingInclTax($amount);
-
-    /**
-     * Sets items for the order.
-     *
-     * @param \Magento\Sales\Api\Data\OrderItemInterface[] $items
-     * @return $this
-     */
-    public function setItems(array $items = null);
-
-    /**
-     * Sets the billing address, if any, for the order.
-     *
-     * @param \Magento\Sales\Api\Data\OrderAddressInterface $billingAddress
-     * @return $this
-     */
-    public function setBillingAddress(\Magento\Sales\Api\Data\OrderAddressInterface $billingAddress = null);
-
-    /**
-     * Sets the shipping address, if any, for the order.
-     *
-     * @param \Magento\Sales\Api\Data\OrderAddressInterface $shippingAddress
-     * @return $this
-     */
-    public function setShippingAddress(\Magento\Sales\Api\Data\OrderAddressInterface $shippingAddress = null);
-
-    /**
-     * Sets the payments for the order.
-     *
-     * @param \Magento\Sales\Api\Data\OrderPaymentInterface[] $payments
-     * @return $this
-     */
-    public function setPayments(array $payments = null);
-
-    /**
-     * Sets addresses for the order.
-     *
-     * @param \Magento\Sales\Api\Data\OrderAddressInterface[] $addresses
-     * @return $this
-     */
-    public function setAddresses(array $addresses = null);
-
-    /**
-     * Sets status histories for the order.
-     *
-     * @param \Magento\Sales\Api\Data\OrderStatusHistoryInterface[] $statusHistories
-     * @return $this
-     */
-    public function setStatusHistories(array $statusHistories = null);
 }

app/code/Magento/Sales/Api/Data/OrderItemInterface.php

@@ -851,6 +851,14 @@ public function getProductId();
      */
     public function getProductOptions();
 
+    /**
+     * Sets the product options for the order item.
+     *
+     * @param string[] $productOptions
+     * @return $this
+     */
+    public function setProductOptions($productOptions);
+
     /**
      * Gets the product type for the order item.
      *
@@ -1054,6 +1062,14 @@ public function getWeight();
      */
     public function getParentItem();
 
+    /**
+     * Sets the parent item
+     *
+     * @param \Magento\Sales\Api\Data\OrderItemInterface $parentItem
+     * @return $this
+     */
+    public function setParentItem($parentItem);
+
     /**
      * Sets the updated-at timestamp for the order item.
      *
@@ -1118,14 +1134,6 @@ public function setProductId($id);
      */
     public function setProductType($productType);
 
-    /**
-     * Sets the product options for the order item.
-     *
-     * @param string[] $productOptions
-     * @return $this
-     */
-    public function setProductOptions(array $productOptions = null);
-
     /**
      * Sets the weight for the order item.
      *
@@ -1789,12 +1797,4 @@ public function setBaseWeeeTaxDisposition($baseWeeeTaxDisposition);
      * @return $this
      */
     public function setBaseWeeeTaxRowDisposition($baseWeeeTaxRowDisposition);
-
-    /**
-     * Sets the parent item
-     *
-     * @param \Magento\Sales\Api\Data\OrderItemInterface $parentItem
-     * @return $this
-     */
-    public function setParentItem($parentItem);
 }

app/code/Magento/Sales/Api/Data/ShipmentInterface.php

@@ -145,6 +145,14 @@ public function getOrderId();
      */
     public function getPackages();
 
+    /**
+     * Sets any packages for the shipment.
+     *
+     * @param \Magento\Sales\Api\Data\ShipmentPackageInterface[] $packages
+     * @return $this
+     */
+    public function setPackages(array $packages = null);
+
     /**
      * Gets the shipment status.
      *
@@ -310,12 +318,4 @@ public function setShippingLabel($shippingLabel);
      * @return $this
      */
     public function setUpdatedAt($timestamp);
-
-    /**
-     * Sets any packages for the shipment.
-     *
-     * @param \Magento\Sales\Api\Data\ShipmentPackageInterface[] $packages
-     * @return $this
-     */
-    public function setPackages(array $packages = null);
 }

app/code/Magento/Sales/Api/Data/TransactionInterface.php

@@ -204,7 +204,7 @@ public function setIsClosed($isClosed);
     /**
      * Additional information setter
      * Updates data inside the 'additional_information' array
-     * Doesn't allow to set arrays
+     * Does not allow setting of arrays
      *
      * @param string $key
      * @param mixed $value