Issue #2980713 by bojanz: Switch order item adjustments from per-unit to per-line rounding

Author: bojanz

modules/order/commerce_order.install

@@ -56,3 +56,20 @@ function commerce_order_update_8203() {
   $update_manager = \Drupal::entityDefinitionUpdateManager();
   $update_manager->installFieldStorageDefinition('locked', 'commerce_order', 'commerce_order', $storage_definition);
 }
+
+/**
+ * Add the 'uses_legacy_adjustments' field to 'commerce_order_item' entities.
+ */
+function commerce_order_update_8204() {
+  $storage_definition = BaseFieldDefinition::create('boolean')
+    ->setLabel(t('Uses legacy adjustments'))
+    ->setSettings([
+      'on_label' => t('Yes'),
+      'off_label' => t('No'),
+    ])
+    ->setDefaultValue(FALSE)
+    ->setInitialValue(TRUE);
+
+  $update_manager = \Drupal::entityDefinitionUpdateManager();
+  $update_manager->installFieldStorageDefinition('uses_legacy_adjustments', 'commerce_order_item', 'commerce_order', $storage_definition);
+}

modules/order/src/Entity/Order.php

@@ -306,7 +306,15 @@ public function clearAdjustments() {
     };
     // Remove all unlocked adjustments.
     foreach ($this->getItems() as $order_item) {
+      /** @var \Drupal\commerce_order\Adjustment[] $adjustments */
       $adjustments = array_filter($order_item->getAdjustments(), $locked_callback);
+      // Convert legacy locked adjustments.
+      if ($adjustments && $order_item->usesLegacyAdjustments()) {
+        foreach ($adjustments as $index => $adjustment) {
+          $adjustments[$index] = $adjustment->multiply($order_item->getQuantity());
+        }
+      }
+      $order_item->set('uses_legacy_adjustments', FALSE);
       $order_item->setAdjustments($adjustments);
     }
     $adjustments = array_filter($this->getAdjustments(), $locked_callback);
@@ -322,9 +330,10 @@ public function collectAdjustments() {
     $adjustments = [];
     foreach ($this->getItems() as $order_item) {
       foreach ($order_item->getAdjustments() as $adjustment) {
-        // Order item adjustments apply to the unit price, they
-        // must be multiplied by quantity before they are used.
-        $adjustments[] = $adjustment->multiply($order_item->getQuantity());
+        if ($order_item->usesLegacyAdjustments()) {
+          $adjustment = $adjustment->multiply($order_item->getQuantity());
+        }
+        $adjustments[] = $adjustment;
       }
     }
     foreach ($this->getAdjustments() as $adjustment) {

modules/order/src/Entity/OrderInterface.php

@@ -234,8 +234,7 @@ public function clearAdjustments();
    * Collects all adjustments that belong to the order.
    *
    * Unlike getAdjustments() which returns only order adjustments, this
-   * method returns both order and order item adjustments (multiplied
-   * by quantity).
+   * method returns both order and order item adjustments.
    *
    * Important:
    * The returned adjustments are unprocessed, and must be processed before use.

modules/order/src/Entity/OrderItem.php

@@ -144,21 +144,9 @@ public function isUnitPriceOverridden() {
   /**
    * {@inheritdoc}
    */
-  public function getAdjustedUnitPrice(array $adjustment_types = []) {
-    if ($unit_price = $this->getUnitPrice()) {
-      $adjusted_price = $unit_price;
-      foreach ($this->getAdjustments() as $adjustment) {
-        if ($adjustment_types && !in_array($adjustment->getType(), $adjustment_types)) {
-          continue;
-        }
-        if ($adjustment->isIncluded()) {
-          continue;
-        }
-
-        $adjusted_price = $adjusted_price->add($adjustment->getAmount());
-      }
-
-      return $adjusted_price;
+  public function getTotalPrice() {
+    if (!$this->get('total_price')->isEmpty()) {
+      return $this->get('total_price')->first()->toPrice();
     }
   }
 
@@ -196,22 +184,82 @@ public function removeAdjustment(Adjustment $adjustment) {
   /**
    * {@inheritdoc}
    */
-  public function getTotalPrice() {
-    if (!$this->get('total_price')->isEmpty()) {
-      return $this->get('total_price')->first()->toPrice();
-    }
+  public function usesLegacyAdjustments() {
+    return $this->get('uses_legacy_adjustments')->value;
   }
 
   /**
    * {@inheritdoc}
    */
   public function getAdjustedTotalPrice(array $adjustment_types = []) {
-    if ($adjusted_unit_price = $this->getAdjustedUnitPrice($adjustment_types)) {
-      $rounder = \Drupal::service('commerce_price.rounder');
+    $total_price = $this->getTotalPrice();
+    if (!$total_price) {
+      return NULL;
+    }
+
+    if ($this->usesLegacyAdjustments()) {
+      $adjusted_unit_price = $this->getAdjustedUnitPrice($adjustment_types);
       $adjusted_total_price = $adjusted_unit_price->multiply($this->getQuantity());
-      $adjusted_total_price = $rounder->round($adjusted_total_price);
-      return $adjusted_total_price;
     }
+    else {
+      $adjusted_total_price = $this->applyAdjustments($total_price, $adjustment_types);
+    }
+
+    $rounder = \Drupal::service('commerce_price.rounder');
+    $adjusted_total_price = $rounder->round($adjusted_total_price);
+
+    return $adjusted_total_price;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getAdjustedUnitPrice(array $adjustment_types = []) {
+    $unit_price = $this->getUnitPrice();
+    if (!$unit_price) {
+      return NULL;
+    }
+
+    if ($this->usesLegacyAdjustments()) {
+      $adjusted_unit_price = $this->applyAdjustments($unit_price, $adjustment_types);
+    }
+    else {
+      $adjusted_total_price = $this->getAdjustedTotalPrice($adjustment_types);
+      $adjusted_unit_price = $adjusted_total_price->divide($this->getQuantity());
+    }
+
+    $rounder = \Drupal::service('commerce_price.rounder');
+    $adjusted_unit_price = $rounder->round($adjusted_unit_price);
+
+    return $adjusted_unit_price;
+  }
+
+  /**
+   * Applies adjustments to the given price.
+   *
+   * @param \Drupal\commerce_price\Price $price
+   *   The price.
+   * @param string[] $adjustment_types
+   *   The adjustment types to include in the adjusted price.
+   *   Examples: fee, promotion, tax. Defaults to all adjustment types.
+   *
+   * @return \Drupal\commerce_price\Price
+   *   The adjusted price.
+   */
+  protected function applyAdjustments(Price $price, array $adjustment_types = []) {
+    $adjusted_price = $price;
+    foreach ($this->getAdjustments() as $adjustment) {
+      if ($adjustment_types && !in_array($adjustment->getType(), $adjustment_types)) {
+        continue;
+      }
+      if ($adjustment->isIncluded()) {
+        continue;
+      }
+
+      $adjusted_price = $adjusted_price->add($adjustment->getAmount());
+    }
+
+    return $adjusted_price;
   }
 
   /**
@@ -337,19 +385,27 @@ public static function baseFieldDefinitions(EntityTypeInterface $entity_type) {
       ->setDescription(t('Whether the unit price is overridden.'))
       ->setDefaultValue(FALSE);
 
+    $fields['total_price'] = BaseFieldDefinition::create('commerce_price')
+      ->setLabel(t('Total price'))
+      ->setDescription(t('The total price of the order item.'))
+      ->setReadOnly(TRUE)
+      ->setDisplayConfigurable('form', FALSE)
+      ->setDisplayConfigurable('view', TRUE);
+
     $fields['adjustments'] = BaseFieldDefinition::create('commerce_adjustment')
       ->setLabel(t('Adjustments'))
       ->setRequired(FALSE)
       ->setCardinality(BaseFieldDefinition::CARDINALITY_UNLIMITED)
       ->setDisplayConfigurable('form', FALSE)
       ->setDisplayConfigurable('view', TRUE);
 
-    $fields['total_price'] = BaseFieldDefinition::create('commerce_price')
-      ->setLabel(t('Total price'))
-      ->setDescription(t('The total price of the order item.'))
-      ->setReadOnly(TRUE)
-      ->setDisplayConfigurable('form', FALSE)
-      ->setDisplayConfigurable('view', TRUE);
+    $fields['uses_legacy_adjustments'] = BaseFieldDefinition::create('boolean')
+      ->setLabel(t('Uses legacy adjustments'))
+      ->setSettings([
+        'on_label' => t('Yes'),
+        'off_label' => t('No'),
+      ])
+      ->setDefaultValue(FALSE);
 
     $fields['data'] = BaseFieldDefinition::create('map')
       ->setLabel(t('Data'))

modules/order/src/Entity/OrderItemInterface.php

@@ -119,36 +119,29 @@ public function setUnitPrice(Price $unit_price, $override = FALSE);
   public function isUnitPriceOverridden();
 
   /**
-   * Gets the adjusted order item unit price.
-   *
-   * The adjusted unit price is calculated by applying the order item's
-   * adjustments to the unit price. This can include promotions, taxes, etc.
-   *
-   * Adjustments are usually included only in the order total price, but
-   * knowing the adjusted unit prices for each order item can be useful for
-   * refunds and other purposes.
-   *
-   * @param string[] $adjustment_types
-   *   The adjustment types to include in the adjusted price.
-   *   Examples: fee, promotion, tax. Defaults to all adjustment types.
+   * Gets the order item total price.
    *
    * @return \Drupal\commerce_price\Price|null
-   *   The adjusted order item unit price, or NULL.
+   *   The order item total price, or NULL.
    */
-  public function getAdjustedUnitPrice(array $adjustment_types = []);
+  public function getTotalPrice();
 
   /**
-   * Gets the order item total price.
+   * Gets whether the order item uses legacy adjustments.
    *
-   * @return \Drupal\commerce_price\Price|null
-   *   The order item total price, or NULL.
+   * Indicates that the adjustments were calculated based on the unit price,
+   * which was the default logic prior to Commerce 2.8, changed in #2980713.
+   *
+   * @return bool
+   *   TRUE if the order item uses legacy adjustments, FALSE otherwise.
    */
-  public function getTotalPrice();
+  public function usesLegacyAdjustments();
 
   /**
    * Gets the adjusted order item total price.
    *
-   * Calculated by multiplying the adjusted unit price by quantity.
+   * The adjusted total price is calculated by applying the order item's
+   * adjustments to the total price. This can include promotions, taxes, etc.
    *
    * @param string[] $adjustment_types
    *   The adjustment types to include in the adjusted price.
@@ -159,6 +152,23 @@ public function getTotalPrice();
    */
   public function getAdjustedTotalPrice(array $adjustment_types = []);
 
+  /**
+   * Gets the adjusted order item unit price.
+   *
+   * Calculated by dividing the adjusted total price by quantity.
+   *
+   * Useful for refunds and other purposes where there's a need to know
+   * how much a single unit contributed to the order total.
+   *
+   * @param string[] $adjustment_types
+   *   The adjustment types to include in the adjusted price.
+   *   Examples: fee, promotion, tax. Defaults to all adjustment types.
+   *
+   * @return \Drupal\commerce_price\Price|null
+   *   The adjusted order item unit price, or NULL.
+   */
+  public function getAdjustedUnitPrice(array $adjustment_types = []);
+
   /**
    * Gets an order item data value with the given key.
    *

modules/order/src/EntityAdjustableInterface.php

@@ -7,6 +7,19 @@
 /**
  * Defines an interface for objects that contain adjustments.
  *
+ * Adjustments store promotions, taxes, fees, shipping costs.
+ * They can be calculated on the order level (based on the order subtotal),
+ * or on the order item level (based on the order item total).
+ *
+ * if $order_item->usesLegacyAdjustments() is true, the order item adjustments
+ * were calculated based on the order item unit price, which was the default
+ * logic prior to Commerce 2.8, changed in #2980713.
+ *
+ * Adjustments are always displayed in the order total summary, below
+ * the subtotal. They are not shown as a part of the order item prices.
+ * To get the order item total price with adjustments included, use
+ * $order_item->getAdjustedTotalPrice().
+ *
  * @see \Drupal\commerce_order\Entity\OrderInterfaceEntity
  * @see \Drupal\commerce_order\Entity\OrderItemInterfaceEntity
  */

modules/order/src/PriceCalculator.php

@@ -126,7 +126,7 @@ public function calculate(PurchasableEntityInterface $purchasable_entity, $quant
     foreach ($processors as $processor) {
       $processor->process($order);
     }
-    $calculated_price = $order_item->getAdjustedUnitPrice();
+    $calculated_price = $order_item->getAdjustedTotalPrice();
     $adjustments = $order_item->getAdjustments();
     $adjustments = $this->adjustmentTransformer->processAdjustments($adjustments);