PrestaShop - actionOrderStatusPostUpdate Hook: Does It Really Fire When It Should?

Question

Good Morning, Stack Overflow!

Quick question. According to the hook documentation (http://doc.prestashop.com/display/PS15/Hooks+in+PrestaShop+1.5), the hook named "actionOrderStatusPostUpdate" is meant to be fired AFTER the order status of an object has already been changed, if I understand correctly?

Thus, I assumed since the orderStatus has already been changed I could safely change it again in my code without any issues. My code contains a conditional block that scans the products in the order the moment it goes to the "Payment Received" status, and if the order contains any "restricted items" it would notify the user and change the order status to "Restricted: (reason)" (ID: 15). When I run the code and the hook fires, I end having the status set and then immediately replaced with "Payment Received".

https://www.dropbox.com/s/uc4ebr2ybytx2ks/Screenshot%202016-03-15%2012.52.47.jpg

Is this normal behaviour for the POST update hook? Since the status is supposed to ALREADY BE CHANGED, why would it change it anyway?

...
} else {
//  Restricted order...
    $order->setCurrentState(15, 1);
...

I have also tried this:

...
$history = new OrderHistory();
$history->id_order = (int) $order_id;
$history->changeIdOrderState(15, (int) $order_id);
...

Is there another way to do this that I can ensure it changes correctly?

EDIT

I am aware of this question that asks the same thing: Prestashop - Change order status when payment is validated, but it is also yet to be answered and is thus of no help to me.

EDIT

The best I can do is to try and explain to logical flow of the code:

1. When the user or anything else changes the status of an order, the hook fires (hookActionOrderStatusPostUpdate) from the module.
2. If the status of the order is "Payment Accepted" continue to the next section, otherwise, do nothing...
3. I then check the order, delivery address, and products in the order for certain flags that I use to mark the order "Restricted" (this includes delivery address, invoice address, certain product features, etc)
4. If the order is restricted a case is created in another system that the company can contact the customer to resolve the restriction after this is done the order should set to order state: "Restricted" (id. 15) to indicate that a restriction applies.
5. If the order is NOT restricted, it's passed along to different system for processing, etc.

Answer 1

The hook actionOrderStatusPostUpdate is executed inside the function OrderHistory->changeIdOrderState() at the very end.

So if you are changing your order status with the function OrderHistory->changeIdOrderState() (which also includes email sending, stock management etc.), the hook actionOrderStatusPostUpdate will be executed.

If you want just to change the ID of the order status, you can use some code like this:

$order = new Order((int)$id_order);        
$order->current_state = (int)$id_order_state;
if ($order->update() && $order->setCurrentState((int)$id_order_state))
{
    // proceed
}
else
{
    // report error
}