Adding a Status History Record to an Order

How to use the zen_update_orders_history function

Zen Cart version 1.5.6 introduced the function zen_update_orders_history, providing a way for both admin and storefront processing to easily update an order’s status-history, e.g. changing an order’s status from Processing to Delivered. That function also, based on the parameters supplied, sends an optional status-update email to the customer, interested admins or both.

The function was initially created for a site-specific change where the processing was ‘interested’ in an order’s change in status. See Notifications Issued for additional information.

Function Interface

The function zen_update_orders_history provides an easy way to update an order’s status-history, with the option of sending an email message to the ordering customer. It takes a bunch of parameters, described below.

int zen_update_orders_history($orders_id, $message = '', $updated_by = null, $orders_new_status = -1, $notify_customer = -1, $email_include_message = true, $email_subject = '', $send_extra_emails_to = '')
  1. $orders_id. Contains the (integer) orders_id of the to-be-updated customer order.
  2. $message. Contains a message-string to be recorded with the status-update.
  3. $updated_by. If the value is not null, then it’s expected to be a string-value that identifies ‘who’ (e.g. an external process) caused the update. Otherwise, the $updated_by value is set based on
    1. … if in the admin, to the current admin-name suffixed by their admin ID, e.g. Dave [5].
    2. … if a customer is logged in, to an empty string.
    3. … if a customer is not logged in, to N/A.
  4. $orders_new_status. Indicates the new status-history value to be applied to an order. A value of -1 indicates no change in status.
  5. $notify_customer. Indicates whether the added status-history record is customer-visible and whether to send an email notification of the change, one of:
    • 0 … No emails are sent; the history-update is visible to the customer.
    • 1 … Emails are sent to the customer and any configured admins; the history-update is visible to the customer.
    • -1 … No emails are sent; the history-update is not visible to the customer.
    • -2 … Emails are sent to any configured admins; the history-update is not visible to the customer.
  6. $email_include_message. A boolean flag that indicates whether or not to include the $message string as part of the to-be-sent email. If false, the message will be recorded in the status-history update only.
  7. $email_subject. A string value, providing an override to the default subject: OSH_EMAIL_TEXT_SUBJECT . ' #' . $orders_id.
  8. $send_extra_emails_to. A string value, providing an override for the database constant SEND_EXTRA_ORDERS_STATUS_ADMIN_EMAILS_TO.

The function returns an integer value, identifying its completion status, one of:

  • -1 … No status-change detected, no orders_status_history record was written.
  • -2 … No order-record was found for the submitted $orders_id.
  • Otherwise, the return value identifies the orders_status_history_id value for the just-written status-history record.

Function Processing

Creating an Order’s Status History Record

The zen_update_orders_history function will create an additional orders_status_history record for the supplied $orders_id if the $orders_id supplied is associated with an orders table record and at least one of the following conditions is met:

  1. The $orders_new_status is set to -1 (no change in status).
  2. The $orders_new_status is different from the order’s current status.
  3. The $message to be recorded is not ’empty’.

Typical Function Call for Plugin Authors/Developers

You have just taken an action that you want recorded in the order status history table. Simply pass in the order id and a string with what you want recorded.

zen_update_orders_history($oID, 'A comment describing the action taken');

No email is sent and the entry is only shown in the admin.

Notifications Issued

The function also provides a collection of notifications, enabling additional store-specific processing.

ZEN_UPDATE_ORDERS_HISTORY_PRE_EMAIL

This notification is issued only when $email_include_message is set to true (i.e. the message is to be included in any sent emails) and provides a watching observer the opportunity to override the current message text:

$GLOBALS['zco_notifier']->notify('ZEN_UPDATE_ORDERS_HISTORY_PRE_EMAIL', array('message' => $message), $osh_additional_comments);

The $osh_additional_comments parameter can be updated to provide additional text to be appended to the $message value for the emails.

ZEN_UPDATE_ORDERS_HISTORY_STATUS_VALUES

This notification is issued if the function has determined that an orders-status-history record is to be created:

$GLOBALS['zco_notifier']->notify('ZEN_UPDATE_ORDERS_HISTORY_STATUS_VALUES', array('orders_id' => $orders_id, 'new' => $orders_new_status, 'old' => $orders_current_status));

The notification identifies the orders-id as well as the order’s new (to-be-written) and current orders’ status values and is the heart of the function’s processing. Essentially the notification provides a means for site-specific changes to be performed when an order’s status changes.

ZEN_UPDATE_ORDERS_HISTORY_SET_ORDER_UPDATE_MESSAGE

This notification is issued prior to sending any email and gives a watching observer the opportunity to override the text sent in that email.

$GLOBALS['zco_notifier']->notify('ZEN_UPDATE_ORDERS_HISTORY_SET_ORDER_UPDATE_MESSAGE', $orders_id, $email_order_message);

ZEN_UPDATE_ORDERS_HISTORY_BEFORE_INSERT

This notification is issued just prior to creating a new orders_status_history record for the order, giving a watching observer the opportunity to make final adjustments, e.g. adding additional fields to the status-history record:

$GLOBALS['zco_notifier']->notify('ZEN_UPDATE_ORDERS_HISTORY_BEFORE_INSERT', array(), $osh_sql);

The $osh_sql is an associative array, submitted to zen_db_perform to create that new record.




Still have questions? Use the Search box in the upper right, or try the full list of FAQs. If you can't find it there, head over to the Zen Cart support forum and ask there in the appropriate subforum. In your post, please include your Zen Cart and PHP versions, and a link to your site.

Is there an error or omission on this page? Please post to General Questions on the support forum. Or, if you'd like to open a pull request, just review the guidelines and get started. You can even PR right here.
Last modified January 12, 2024 by Scott C Wilson (2e7ec20a).