Magento Recommended way to add comment to order

Question

I am looking for the Magento recommended best practice for adding a comment to an order. I can easily accomplish this using things such as $order->addCommentToStatusHistory($message)->save() and similar actions. However I know that using a direct save action is not recommended on models and you should instead us managers/repositories.

I have also found that there is a \Magento\Sales\Api\OrderStatusHistoryRepositoryInterface now which provides the save function. So what I'm trying to figure out is how to approach this properly. This is my best guess.

private $orderStatusHistoryRepository;

public function __construct(
    \Magento\Sales\Api\OrderStatusHistoryRepositoryInterface $orderStatusHistoryRepository
) {
    $this->orderStatusHistoryRepository = $orderStatusHistoryRepository;
}

public function myFunction(\Magento\Sales\Api\Data\OrderInterface $order)
{
    //... additional logic here
    $history = $order->addCommentToStatusHistory($message);
    $this->orderStatusHistoryRepository->save($history);
}

What I'm not certain about is if this is the proper approach AND should I also be saving the order using OrderRepositoryInterface, or if that is unnecessary.

I have looked through a lot of questions and answers around this as well as looking through some tutorials and documentation. However all of these provide conflicting information and most of them recommend ways that I know are not Magento best practice.

If there is documentation out there that would answer my question and I have overlooked it please point me in the right direction.

This is for Magento 2.3.0.

Answer 1

As per as, current Magento code, there is two way we can save comment

Using Order repository : Magento\Sales\Api\OrderStatusHistoryRepositoryInterface:save()

Using Order history: Magento\Sales\Api\OrderRepositoryInterface:save() and \Magento\Sales\Api\Data\OrderInterface::addCommentToStatusHistory

What is between two:

OrderStatusHistoryRepositoryInterface:save directly related with sales_order_status_history .It is behavior same like basic Crud service contact provider with the model and table. Like How to implement service contract for a custom module in Magento 2?

$history =$this->historyFactory->create();
$history->setParentId($orderid)
     ->setStatus($status)
      ->setComment($comment)
        ->setIsVisibleOnFront($isVisibleOnFront)
        ->setIsCustomerNotified($customerNotifiedflag)
        ->setCreatedAt($createdAt);
$this->OrderStatusHistoryRepository->save($history);

And where to save using Magento\Sales\Api\OrderRepositoryInterface:save() is behavior same like first but as for save for order comment you have to call other function addCommentToStatusHistory() of Magento\Sales\Model\Order

$orderId  = 1;
/**
 * orderRepository instance of  Magento\Sales\Api\OrderRepositoryInterface
 */
$order = $this->orderRepository->get($orderId);
/**
 * $order is instead of  Magento\Sales\Model\Order or \Magento\Sales\Api\Data\OrderInterface
 */
$order->addCommentToStatusHistory('my command', $status = false, $isVisibleOnFront = true);
$this->orderRepository->save($order);

Second different and most important:

For OrderStatusHistoryRepositoryInterface:save() ,you have to send order status code to SetStatus() and it does not change Magento order status as it directly related with Order Service contact or order resource model. and its only perform single table operations.

Where order repository save() can changes order status if you send order status to addCommentToStatusHistory($comment,$OrderStatusCode,$isVisibleOnFront)

As per as,my idea, If you want to only add order command and you have already requirement like $orderid,$status,$isVisibleOnFront etc